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 inmultiserver.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
- Admin Console display
- Viewing status information
- Using the Admin Console
- Adding an application
- Stopping an application
- Deleting an application
- Modifying the configuration of an application
- Debugging an application
- Saving the state of the Multiserver
- Stopping and restarting the Multiserver
- Creating a WAR file
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:
- Type the following command at the command prompt to start the Multiserver:
<enhydra_root
>/bin/multiserverwhere
enhyra_root
is the root of your Enhydra installation. Invoking the multiserver command without giving ita 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.
- 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
![]()
As shown in Figure B.1, "Admin Console display," the Admin Console is divided into two frames:
- The control frame on the left contains the console buttons and the Applications list box (or window).
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.
- The content frame on the right displays information about the application that is currently selected in the Applications window. Some Admin Console functions are accessed from the content frame to display information or to request input.
Note: There are two kinds of Web applications:
- Enhydra super-servlet applications, created with Enhydra development tools
- Servlet applications, otherwise known as WAR files (see "Creating a WAR file")
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
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.
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
![]()
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
![]()
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
- Stopping an application
- Deleting an application
- Modifying the configuration of an application
- Debugging an application
- Saving the state of the Multiserver
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:
- Copy the application's configuration file from the application's root directory to
/
<enhydra_root>
/apps/
. For example:cp simpleApp.conf /usr/local/lutris-enhydra3.5b1/apps/
- In the new
simpleApp.conf
file, locate theserver.Classpath
variable. Comment out the first line, and uncomment the second line. Set theserver.Classpath
variable equal to the new absoluteCLASSPATH
.#server.Classpath[] = ../classes
Server.Classpath[] = "/enhydra/myapps/simpleApp/output/archive/simpleApp.jar"
- 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
![]()
- 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.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.
- 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
![]()
- 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)
- 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."
- 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
![]()
- 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.
- 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:
- 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
![]()
- Click Create in the Connections tab section to display the Add New Connection dialog box.
Figure B.8 Add New Connection dialog box
![]()
- 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.
- 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 applicationhttp://localhost/examples
.
- 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.
- 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.
- 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 inenhydra_director.conf
, and HTTP Server URL, which specifies the URL of the application as set inenhydra_director.conf
, are optional.
- Click OK to return to the Status window.
- To start the application, make sure it is selected in the Applications window, and click the Start button.
- 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:
- Select the application in the Applications window.
- Click the Stop button to stop the application.
- Click the Delete button to delete it from the current session of the Multiserver.
- 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:
- Select the application in the Applications window.
- Click the Modify button.
The Content frame displays the Modify window, as shown in Figure B.9.
Figure B.9 Modify Configuration window
![]()
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:
- Application tab to add additional
CLASSPATHs
for the application or servlet
- Sessions tab to modify Session Manager parameters
- Database tab to modify the database connection.
- Advanced tab to modify the application's default URL.
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:
- Select the desired application in the Applications window.
- Click the Debug button to display the debugging control panel, as shown in Figure B.10
Figure B.10 Debugging control panel
![]()
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:
- 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.
- 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:
Stopping and restarting the Multiserver
Stopping the Multiserver terminates all running applications as well as the Admin Console itself.
- Click the Multiserver Stop button in the control frame, then click OK to confirm.
- To restart the Multiserver, return to the Enhydra shell and proceed as directed in "Launching the Admin Console."
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 calledHello.java
. Set up the following directory structure:/tmp/webApp myJspDir Hello.jsp WEB-INF classes Hello.class web.xmlThe 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 namedmyJspDir
.WEB-INF,
the one required subdirectory, contains the configuration fileweb.xml
and a directory calledclasses
which in turn contains the compiled servlet classes. If you are only using JSPs, you do not need aclasses
subdirectory. The Multiserver adds theclasses
directory to itsCLASSPATH
, 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. Theweb.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 prefixmyPrefix
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 theWEB-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. |
Lutris Technologies http://www.lutris.com 1200 Pacific Avenue Suite 300 Santa Cruz, CA 95060 Voice: (831) 471-9753 Fax: (831) 471-9754 |