Multiserver Administration Console

The Enhydra Multiserver Administration Console, also called the Admin Console, is a built-in component of the Multiserver itself. The Multiserver is a servlet runner that runs Enhydra applications, Java servlets, and JavaServer Pages (JSPs). The Multiserver can accept direct HTTP requests or requests forwarded from a Web server by Enhydra Director. It has controls that allow you to add, remove, start, stop, configure, and monitor your applications.

An Enhydra Multiserver installation typically consists of a directory containing applications, a configuration file called multiserver.conf, and a script to start the Multiserver. The Admin Console, which is actually just another Enhydra application running on the Multiserver, gives you access to the server and allows you to set properties defined in multiserver.conf.

For additional information, see Chapter 3, "Using the Multiserver Administration Console," of the Developer's Guide.

This help file contains the following topics:

Launching the Admin Console

The Admin Console is an Enhydra application that allows you to add, remove, and configure applications to run with Enhydra.

Starting the Admin Console

To launch the Admin Console, follow these steps:

  1. Type the following command at the command prompt to start the Multiserver:
    <enhydra_root>/bin/multiserver
    

    where enhyra_root is the root of your Enhydra installation. Invoking the multiserver command without giving it a multiserver.conf as an argument brings up the server in the default installation.

    Note: If the Admin Console does not start, the path environment variable is not set correctly. The Lutris Enhydra installation instructions provide information about setting your path environment variable. The installation instructions are available in HTML format only on the Lutris Enhydra CD (refer to the top-level index.html) or the Lutris Documentation home page: http://www.lutris.com/documentation/index.html.

  1. In your browser, display the console by entering this URL:
    http://localhost:8001/
    

  1. The console displays a password dialog box, as shown in Figure B.1. To get started, enter the default user name, admin, and password, enhydra. See Chapter 3, "Using the Multiserver Administration Console," of the Developer's Guide for information on changing these settings.

    The Admin Console appears in your Web browser as shown in Figure B.1, "Admin Console display."

    Figure B.1    Admin Console display

    [Picture]

Admin Console display

As shown in Figure B.1, "Admin Console display," the Admin Console is divided into two frames:

    The Applications window contains a list of all the applications, servlets, and Web archives (WARs) available in the Enhydra Multiserver. The console buttons below the Applications window initiate operations on the selected application.

Note: There are two kinds of Web applications:

Control frame

As shown in Figure B.1, "Admin Console display," the control frame has two components, an Applications window and the console buttons. Both components are described in the following sections.

Applications window
The Applications window contains a list of all applications currently available in the Enhydra Multiserver. You will see three sample applications that are initially available:

Admin Console buttons
Table B.1 describes the function of each button in the control frame (see Figure B.1).

Table B.1    Admin Console buttons 

Button Description
Start Starts the application currently selected in the Applications window. Unavailable when the selected application is already running.
Stop Stops the application that is selected in the Applications window. If the application has active users, you are prompted to verify that you want the application stopped.
Add Adds an application to the Enhydra Multiserver.
Delete Removes the selected application from the Enhydra Multiserver.
Modify Modifies the configurable attributes of the selected application.
Debug Invokes the debugging utility for the selected application. When you click this button, the debugging control panel displays.
Save State Saves the state of the Enhydra Multiserver.
Multiserver Stop Stops the Enhydra Multiserver.

Content frame

As shown in Figure B.1, the content frame displays information relevant to the current activity of the Multiserver, typically showing Status, Modify, or Debug windows with their various tab sections. The information you see in these screens varies with the type of application (Enhydra application, servlet, or Web archive), and with the specifics of the current task.

Viewing status information

To display status information about an application, select its name in the Applications list box (See Figure B.1). The Status window appears in the content frame, containing an Applications tab and a Connections tab. Figure B.2 shows a portion of the Status window for the sample Welcome application.

Note: The elements of the screen will be somewhat different for a servlet or WAR.

The Application tab contains information about the application including its CLASSPATH, session manager status, database manager status, and traffic statistics.

Figure B.2    Status display for an application

[Picture]

Viewing connections status information
Click the Connections tab to display connection status information for the application. Connections represent channels for requests coming into the application. For example, an application could be receiving direct HTTP requests on port 8000 and requests coming from a Web server via an Enhydra Director connection on port 8020. Figure B.3 shows an example of the connection status display for an application receiving direct HTTP requests.

Figure B.3    Connection status display for a running application

[Picture]

Using the Admin Console

This section describes how to use the Admin Console to work with your Enhydra applications and servlets. This section provides information on:

Adding an application

This section describes how to add an Enhydra super-servlet application, a single servlet, or a servlet application set up as a Web Archive (WAR) to the list of applications running on the server.

Note: A WAR is a collection of servlets bound together for convenient administration. Using the Admin Console, you can add a WAR to the Multiserver in just a few steps. For convenience, we recommend that you bundle your servlets into a WAR and add them all in one process--see "Adding a servlet application configured as a WAR."

Adding an Enhydra super-servlet application
Follow these steps to add an Enhydra application to the Multiserver:

  1. Copy the application's configuration file from the application's root directory to /<enhydra_root>/apps/. For example:
    cp simpleApp.conf [Enhydra_root]/apps/
    

  1. In the new simpleApp.conf file, locate the server.Classpath variable. Comment out the first line, and uncomment the second line. Set the server.Classpath variable equal to the new absolute CLASSPATH.
    #server.Classpath[] = ../classes
    Server.Classpath[] = "/enhydra/myapps/simpleApp/output/archive/simpleApp.jar"
    

    Then save and close the configuration file.

  1. Click the Add button to display the Add New Application/Servlet dialog box, and select the Application radio button if it's not already selected.

    Figure B.4    Add New Application/Servlet dialog box

    [Picture]

  2. Select the name of your application from the pull-down list.

    An application's name only appears in the list if its configuration file is in the <enhydra_root>/apps directory, and if it has not already been added to the Multiserver.

    Optionally, enter a description.

  1. Click OK to add your application to the Multiserver.

Adding a single servlet
This section describes how to use the Admin Console to add a single servlet to the Multiserver.

Note: We recommend that you set up your servlet application as a WAR file. The following instructions, however, explain how to add a servlet not set up as a WAR file.

  1. Click the Add button to display the Add New Application/Servlet dialog box, and select the Servlet radio button.

    Figure B.5    Add New Servlet dialog box

    [Picture]

  2. In the fields provided, enter:

    • Name of the servlet

    • Name of the class to instantiate for the servlet

    • Any additional classpaths required for the servlet

    • Root of the servlet's file system on disk

    • Any initial arguments for the servlet (optional)

    • Description of the servlet (optional)

  3. Click OK to add your application to the Multiserver.

Adding a servlet application configured as a WAR
This section describes how to use the Admin Console to add a WAR file to the Multiserver. For information on creating a WAR, see "Creating a WAR file."

  1. Click the Add button to display the Add New Application/Servlet dialog box, and select the WAR radio button.

    Figure B.6    Add New WAR dialog box

    [Picture]

  2. In the fields provided, enter:

    • Name of the archive, not necessarily the file name.

    • Doc Root--path to the root directory of the Web archive after it's unzipped.

    • Session Timeout--period of time, in seconds, for which the session may remain idle before timing out.

    • War Expanded--leave selected; all WARs must be expanded in this release.

    • War Validated--leave selected; see Tomcat documentation for details.

    • Invoker Enabled--select if you want to use /servlets/* syntax.

    • WarDir Persistent--select if you want to save the work directory after the termination of the current Multiserver session. The work directory is where the Multiserver saves compiled JSPs. If you stop the Multiserver with Ctrl-C, you may want to manually remove the work directory before restarting the server to avoid reuse of previously compiled JSPs.

    • Description--plain English description of this archive.

  3. Click OK to finish adding the WAR to the Multiserver.

Specifying a connection method
Once you have added your application, you must establish a connection method for the item you've just added. To do that, follow these steps:

  1. With the application selected in the Applications list box, click the Connections tab in the content frame.

    Figure B.7    Live connection in the Connections tab

    [Picture]

  2. Click Create in the Connections tab section to display the Add New Connection dialog box.

    Figure B.8    Add New Connection dialog box

    [Picture]

  3. For Connection Method, choose

    • HTTP for a standard Web connection, typically in a development environment.

    • HTTPS for a secure Web connection, also in a development environment. This option is only available if you have configured your Enhydra installation with Sun's Java Secure Socket Extension Kit. For more information, see Appendix A, "Using SSL with Enhydra" of the Developer's Guide.

    • Enhydra Director for connection via a Web server. See Chapter 9, "Using Enhydra Director," of the Developer's Guide for further information.

  4. Enter a URL Prefix to define the portion of the URL that precedes the application. For example, the demonstration uses an URL prefix of /examples, making the full URL to the application http://localhost/examples.

  5. For Bind Address, enter an IP address if you want to bind to only one of the available IP addresses on a a given machine. If no IP address is specified, the server binds the given port for all IP addresses on the machine.

  6. For Port Number enter an unused port number. Note that you must be root to bind to ports numbered below 1024 on UNIX systems. You may want to check that a given port is not already in use with the UNIX command netstat. The highest valid port number is 65535.

  7. If your connection method is EnhydraDirector, three new configuration options are available: Session Affinity, Authentication Key, and HTTP Server URL. Session Affinity specifies whether Director will attempt to preserve session affinity in your application. Authentication Key, which specifies the password for the application if it was configured to use authentication in enhydra_director.conf, and HTTP Server URL, which specifies the URL of the application as set in enhydra_director.conf, are optional.

  8. Click OK to return to the Status window.

  9. To start the application, make sure it is selected in the Applications window, and click the Start button.

  10. Click Save State to add the item permanently to the Multiserver. This overwrites the Multiserver's configuration file, multiserver.conf.

Stopping an application

To modify or delete an application, you must first stop it. To do so, select the application's name in the Applications list box, and click the Stop button.

In some situations, such as when users are still connected, you will be prompted to confirm your decision.

Deleting an application

When you remove an application from the Multiserver, you are not deleting the application or its configuration file from your computer. You are simply removing it from the Multiserver's configuration file.

Follow these steps to delete an application from the Multiserver:

  1. Select the application in the Applications window.

  2. Click the Stop button to stop the application.

  3. Click the Delete button to delete it from the current session of the Multiserver.

  4. Click the Save State button to overwrite the Multiserver configuration file and make the change permanent.

Modifying the configuration of an application

To modify an application, you must first stop it by using the Stop button. You can then edit parameters for the application. In the case of an Enhydra application, you can edit the application's configuration file using the Admin Console.

Use the following steps to modify the configuration of an application in Multiserver:

  1. Select the application in the Applications window.

  2. Click the Modify button.

    The Content frame displays the Modify window, as shown in Figure B.9.

    Figure B.9    Modify Configuration window

    [Picture]

The Modify Configuration window features tabs that you can use to modify the application or servlet. If you are modifying an application, you can choose from among four tabs. Use the:

If you are modifying a servlet, there is only one tab--the Servlet tab. You can use the Servlet tab to modify the configuration options for the servlet, which are the same options that you specify when adding the servlet.

For more information about the available configuration parameters, see Chapter 3, "Using the Multiserver Administration Console," of the Developer's Guide.

Debugging an application

The debugging tool that comes with the Enhydra Multiserver is not a debugger in the classic sense of allowing you set breakpoints and step through your code. It is actually a traffic "snooper" that lets you see the requests going into your application and the responses being sent back. This capability can be very helpful for debugging HTTP-related issues when it is not always clear what is in the request coming from the client.

Use the following steps to debug an application running in the Multiserver:

  1. Select the desired application in the Applications window.

  2. Click the Debug button to display the debugging control panel, as shown in Figure B.10

    Figure B.10    Debugging control panel

    [Picture]

    As shown in Figure B.10, the scrolling area in the window shows the active event list. You can use the debugging buttons as follows:

    • Click the Pause button to pause the debugging function, which stops the accumulating of events in the scroll list.

    • Click the Resume button to resume the debugging function.

    • Click the Clear button to clear the list of events.

    • Click the Finish button to halt debugging and close the popup window.

  1. Make three to five requests to your application using a browser. The active event list in the scrolling lower portion of the debugger window will list the requests as they come in. The method name is captured for each request.

  2. Click the name of the response type--GET in the above example--to display the Debug window in the content frame, with its tab sections of Request, Trace, Sessions, and Response. Use this information as needed in monitoring, debugging, or modifying your application.

Saving the state of the Multiserver

When you add or delete applications or servlets with the Console, you are changing the current configuration of the Multiserver. If you want the changes to be retained, you must save the configuration.

Use the following steps to write the current configuration to the Multiserver configuration file:

  1. Click the Save State button.

  2. Click OK in the Confirmation dialog box.

Stopping and restarting the Multiserver

Stopping the Multiserver terminates all running applications as well as the Admin Console itself.

Creating a WAR file

This section describes how to set up the directory structure of a WAR file to deploy Java servlets, JSPs, and static content. Under the Servlet 2.2 API, JSPs and servlets are assembled into a directory structure referred to as a Web application archive, or WAR. When the WAR is finished, you can compress it into a file with a .war extension. Once set up, it can be moved from server to server without further configuration. A good way to understand how to construct a WAR is to look at a simple example.

A simple WAR example

Suppose you want to deploy a JSP called Hello.jsp and a servlet called Hello.java. Set up the following directory structure:
/tmp/webApp
   myJspDir 
      Hello.jsp
   WEB-INF
      classes
         Hello.class
      web.xml 

The directory structure begins with a document root directory that has an arbitrary name, in this case, webApp. The JSP page can be placed either in the document root directory or in any of its subdirectories. In this example, it is placed in an arbitrary subdirectory named myJspDir. WEB-INF, the one required subdirectory, contains the configuration file web.xml and a directory called classes which in turn contains the compiled servlet classes. If you are only using JSPs, you do not need a classes subdirectory. The Multiserver adds the classes directory to its CLASSPATH, so the server automatically finds servlets placed in that directory.

The last required file, web.xml, contains deployment information like name mappings, parameters, and default file mappings. The web.xml file in this simple example contains the following essentially empty file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
    
<web-app>
    <!-- configuration options would go here -->
    
</web-app>

Once you register your Web application with the Multiserver, you access the above pages with the following URLs:

The http://<your_host> section of the URL represents your host machine. When you configure the Multiserver to run the servlet, you tell it that the path to the document root is /tmp/webApp, and the URL prefix is some arbitrary string like /myPrefix. Therefore, every request with the prefix myPrefix is forwarded to the Multiserver which in turn runs your application.

The remainder of the URL for the JSP page corresponds to the directory structure. You can put HTML files in the same directory and request them in a similar manner. Calls to the servlet require the reserved word "servlet" in the URL. When the servlet server sees it, it knows to look for the corresponding class in the classes subdirectory of the WEB-INF directory.

For more information

For a somewhat more complex example, see the WarExample application that ships with Enhydra. Beyond that, Sun's Servlet 2.2 specification provides more information about configuring a WAR, containing both instructions and examples. You can download it from http://java.sun.com/products/servlet/download.html.

For a more in-depth discussion on using the Admin Console with WAR files, see Chapter 3, "Using the Multiserver Administration Console" in the Developer's Guide.


Copyright © 2000 by Lutris Technologies, Inc. All rights reserved.
No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from Lutris Technologies, Inc.

Lutris Technologies
http://www.lutris.com
1200 Pacific Avenue
Suite 300
Santa Cruz, CA 95060
Voice: (831) 471-9753
Fax: (831) 471-9754