Sample J2EE Applications

Chapter 4   HTML SMC

The HTML SMC is a J2EE sample application developed using the Struts Framework. It demonstrates a J2EE implementation of the SilverStream Management Console (SMC) that you can run in a browser.

CAUTION   It is not recommended that you run the HTML SMC against your production SilverStream server. This sample application will change a server's administrative configuration settings and is not intended for production use.

This page covers the following topics:

• Differences between the production SMC and the HTML SMC

• How the HTML SMC isolates vendor specifics

• The HTML SMC implementation model

• Technologies used in the HTML SMC

• Running the HTML SMC

Differences between the production SMC and the HTML SMC

The HTML SMC includes configuration pages for the General, Advanced, Database, Mail, and Connections options, not for the Monitor and Security options.

Production SMC   The SilverStream Management Console installed with the SilverStream server is a Java client application that uses Silver JRunner to run SilverStream forms. These forms are stored in the SilverMaster database and enable you to administer the server.

    See the Administrator's Guide for more information about using the SMC.

HTML SMC    The HTML SMC is a J2EE archive-based application installed in the SilverMaster database (though you can choose to use a different database). Like the production SMC, the HTML SMC uses information stored in the SilverMaster database and the httpd.props configuration file to manage server settings. Unlike the production SMC, the HTML SMC uses standard J2EE technology--including JSPs that execute in containers on the server using a browser-based interface.

How the HTML SMC isolates vendor specifics

The SMC HTML demonstrates how you can optimize the portability of J2EE applications that need to use vendor-specific code. Although the HTML SMC is implemented using standard J2EE architecture, it also includes some vendor-specific API code. It uses the SilverStream Admin API to manage SilverStream server settings because the current J2EE specification does not provide a standard administration API. However, the HTML SMC's administration module, which is contained in separate classes, allows the application developer to easily add, customize, or replace this module.

The HTML SMC implementation model

The HTML SMC is implemented using the Struts Framework architecture. Struts is an open-source framework for Web applications that implements the Model-View-Controller (MVC) design paradigm. As an application that conforms to this paradigm, the HTML SMC includes the following elements:

Component	Description
Model	The application's internal state and persistent data, plus the actions taken to change the persistent data, which is represented by the SMC server settings.
View	JavaServer Pages (JSPs) that use custom tag libraries to render the front-end interface. These JSPs insert dynamic content based on the interpretation of action tags at page request time.
Controller	An action servlet that dispatches requests to action classes to perform actions, such as retrieving configuration data from the SilverStream server. The action servlet uses action mappings to navigational entry points after the action is completed.

The major benefit of the MVC approach is that it logically separates the key functions of the application--actions, data access, and presentation--to allow role-specific assignments, ease of maintenance, and efficient debugging.

Technologies used in the HTML SMC

The HTML SMC incorporates the following J2EE standard technologies to implement the Struts Framework and MVC design paradigm:

• JavaServer Pages

• Action servlets

• ActionForm classes

• Admin API helper classes

NOTE   The HTML SMC sample application does not use EJBs because it does not need to retrieve and maintain data from an external JDBC data source.

    For more information about the Struts Framework and the MVC design paradigm, see the Jakarta project Struts Framework Web site.

JavaServer Pages

JavaServer Pages (JSPs) are used to implement the View component of the MVC design paradigm. JSPs provide both the static and the dynamic content of the HTML SMC's configuration panels.

Static   The following two JSPs display data that changes infrequently if at all in HTML SMC:

• Top-level menu bar (shows the Configuration icon and the Start and Stop action buttons)

• Options menu bar (shows General, Advanced, Database, and so on)

Because the top-level and options menu bars never change, these two JSPs are implemented as JSP include pages (as seen in the following code excerpt from SMCGeneral.jsp) and are reused throughout the application.

  <% /* Include SMC Top-level Menu  */ %> 
  <%@ include file="SMCTopMenu.jsp" %> 
  
  <% /* Include SMC Navigation Menu  */ %>
  <%@ include file="SMCOptionsMenu.jsp" %>

The include statement shows the two JSP files shared by the HTML SMC's General form. The include statement determines the application actions that occur when navigational processing is successful.

Dynamic   The HTML SMC uses dynamic JSPs to present setting details (such as the new mail account configuration screen).

    For more information about JSPs, see the chapter on using JavaServer Pages in the Programmer's Guide of the server's Classic Development Help.

Action servlets

The action servlet is the cornerstone of the Controller component of the MVC design paradigm. In the HTML SMC, the action servlet performs three key functions:

1. Receives requests from the client--in this case an administrator interacting with the HTML SMC application in a Web browser

2. Determines the action to perform and forwards control to the corresponding JSP page

3. Delegates to an appropriate View component the responsibility for producing the next part of the user interface

Two XML specification files (web.xml and action.xml) are used to configure the HTML SMC action servlet. The specification in web.xml associates the URL pattern *.do with the action servlet so that any URL request or post ending in .do will go to the action servlet for processing.

The specification in action.xml maps each possible client request to an action class that performs the appropriate business logic or handles the possible exceptions. For example, here is one of the URL action mappings in action.xml:

  <action path="/SMCGeneral"
      actionClass="com.sssw.smc.comp.action.SMCGeneralAction" 
      formAttribute="generalForm"
      formClass="com.sssw.smc.comp.form.SMCGeneralForm"
      inputForm="/SMCGeneral.jsp">
  <forward name="success" path="/SMCGeneral.jsp" />
  </action>

When the URL SMCGeneral.do is requested, the action servlet uses an instance of the SMCGeneralAction class (if one already exists) or instantiates a new one to display the SMC navigation entry point or detail selected by the user. The entry point is passed as a parameter on the URL. This action class has access to a forward-mapping address called success which is mapped to the relative URL SMCGeneral.jsp.

ActionForm classes

ActionForm classes represent the Model component of the MVC design paradigm. For example, SMCGeneral.jsp contains form tags that are handled by the SMCGeneralForm class. These tags make up the Struts form. The SMCGeneralForm class displays configuration data about the SilverStream server.

The SMCGeneral form has a corresponding SMCGeneral bean for the entry field values input by the user. This SMCGeneral action bean class remembers user data that is sent to the server.

There are two types of ActionForm classes: ActionForm and ValidatingActionForm. The SMC only uses the ValidatingActionForm class. ValidatingActionForm defines a validate() method that the HTML SMC will use to validate user input. When user input is received, the HTML SMC's validate() method is called to ensure the accuracy of the information.

Admin API helper classes

The following Admin API helper classes modify HTML SMC settings:

• SMC_Config

• SMC_Config_Group

• SMC_Param

These helper classes simplify the logic used to retrieve and save server settings. Rather than being embedded directly in the application, SilverStream Admin API calls are stored separately in these helper classes. This way the HTML SMC's logic can be localized more easily.

Running the HTML SMC

Before you can run the HTML SMC, you need to deploy it in a SilverStream database. Unlike sample applications like SilverBooks, there is no application database data associated with the HTML SMC other than the deployment WAR file.

The following deployment procedure assumes you are using the SilverMaster database to load the WAR file. You must start the HTML SMC from SilverMaster's root directory (because that's where the application deployment plan installs it). The HTML SMC is listed at the root level of the SilverMaster database in the browser. If you want to deploy the HTML SMC sample application to a directory path other than the root, you will need to modify the smc-depl-plan.xml file that runs SilverCmd.

The HTML SMC sample application is located under the samples directory for both the NT and UNIX installs. For example: \SilverStream_install\Samples\SMCStruts.

To deploy the HTML SMC:

1. Start the SilverStream server.

2. At the Windows command prompt, enter the following command to run the deploysmc.bat batch file:

     deploysmc servername:port databasename adminuser adminpassword 
   

   Command-line options:

   • Your server name, port number, and database name are required.

   • Specify the SilverMaster database unless you prefer to use a different database.

   • If you installed the SilverStream server in restricted mode, you must also specify a user name and password. In order to deploy applications, make sure the user account you specify has security permission to modify server configuration.

   NOTE   Use the deploySMC.sh file if you are deploying the HTML SMC in a UNIX environment.

To run the HTML SMC:

1. Open your browser.

   NOTE   You cannot run the HTML SMC from the Designer.

2. Enter this URL:

     http://server/smc
   

   The HTML SMC General page opens in your browser and /SMCInit.do?action=generalForm is appended to the URL.

   

3. Interact with the HTML SMC application. For example:

   • Enable new listening port numbers

   • Enable trace logging

   • Configure debugging

   • Change database connections

   • Modify database connections

   • Set up a new mail account

CAUTION   Any changes you make with the HTML SMC sample application will affect your SilverStream server's administrative settings. If you don't want to save these changes, be sure to return the settings to their original values before you close the browser session.

Sample J2EE Applications

Copyright © 2001, SilverStream Software, Inc. All rights reserved.