Writing servlets for EAServer  Web application support

Chapter 22: Creating Java Servlets

Installing and configuring servlets

After you have created or obtained the Java class that implements your servlet’s functionality, you must define a new servlet in EAServer Manager, associate it with your class, then configure the properties that control how the servlet’s class is loaded and executed.

Installing servlets

In EAServer Manager, servlets that are installed in EAServer display in the Installed Servlets folder under the server’s icon. All servlets that have been defined are displayed in the top-level Servlets folder. You must install a servlet in a server before that server’s clients can execute the servlet.

Defining a new servlet

When defining a new servlet, you can install it in a server at the same time, or you can define the servlet in the top-level Servlets folder, then install it in one or more servers later.

  1. To create a servlet and install it in a server:

    To define a servlet that is not installed in a server:

  2. Enter a name for the servlet. This name will be used in HTTP URLs that invoke the servlet.

  3. Configure the servlet properties as described in “Configuring servlet properties”.

Installing existing servlets into a server

You must install servlets in a server before that server’s clients can invoke the servlet. You can install a servlet into multiple servers. To install a servlet into a server:

  1. Expand the server’s icon, then highlight the Installed Servlets folder within it.

  2. Choose File | Install Servlet.

  3. In the Servlet Wizard, click Install an Existing Servlet.

  4. In the Install Servlet dialog box, highlight the servlet to be installed, then click Ok.

Uninstalling servlets from a server

Uninstalling a servlet from a server makes that servlet unavailable to clients of that server. The server definition persists in EAServer Manager, under the top level Servlets folder. To uninstall a servlet:

  1. Expand the server’s icon, then highlight the Installed Servlets folder within it.

  2. Highlight the servlet to uninstall.

  3. Choose File | Remove Servlet.

Deleting servlet definitions

Deleting a servlet from the top-level Servlets folder removes it entirely from EAServer Manager. To delete a servlet definition:

  1. Expand the top-level Servlets folder.

  2. Highlight the servlet to delete.

  3. Choose File | Delete Servlet.

Configuring servlet properties

The settings in the Servlet Properties dialog box specify the Java class for the servlet and control how EAServer loads and runs instances of the class. The dialog contains the tabs described below.

General settings

Properties on the general tab define the basic information required to load and run the servlet.

Table 22-1: General Tab Settings

Control Name



An optional comment describing the servlet.

Servlet’s fully qualified class name

The name of the Java class that implements the servlet functionality, in Java dot notation; for example, com.sybase.jaguar.DemoServlet.

In a Web application, you can map a servlet name to either a servlet class or a JSP file.

Load during startup

Choose Yes if the servlet must be loaded and initialized when the server starts. If you choose No, the class is loaded when the first client requests to run the servlet. Classes that perform lengthy processing in the init method can be loaded at start-up so that the first client to invoke the servlet does not experience increased response time.

If you choose Yes, servlets are reloaded when you refresh the Web application.

Startup load sequence position

EAServer loads servlets serially. If you choose Yes, to load the servlet during startup, define the order, relative to other servlets in the application. To load the servlet first, enter 1.

Web component type

Choose Servlet or JSP

Init-Args settings

Servlets may require initialization parameters that are specified outside of the source code. For example, you might specify the name of an EAServer connection cache as an initialization parameter. You can use the Init-args properties to define optional initialization parameters for the server.

The Init-Params tab lists the initialization parameters that have been defined for the servlet. Click Add to define a new initialization parameter. Enter the parameter name and the text of the value. The servlet can retrieve the value as a Java String, as explained below. To change a parameter’s value, highlight the parameter in the list, then click Modify. To remove a parameter, highlight it, then click Delete.

Your servlet’s init method can retrieve the specified settings using the ServletConfig.getInitParameter(String) and ServletConfig.getInitParameterNames() methods. The following code fragment shows how:

void init(ServletConfig config) throws ServletException {
  Enumeration paramNames =     config.getInitParameterNames();
  while (paramNames.hasMoreElements())
    String name = (String) paramNames.nextElement();
    String value = config.getInitParameter(name);

Threading settings

By default, EAServer loads one instance of a servlet class and calls methods from multiple threads—to service multiple clients, multiple threads may call the service method simultaneously. If an instance of your servlet cannot safely execute in multiple threads, you must configure the Threading tab to specify that the servlet class is single threaded. You can also specify how EAServer should serialize invocations of the service method for a single-threaded servlet.

Check the Single Threaded option if calls to your servlet’s service method must be serialized. When this option is selected, you can specify the number of instances that EAServer creates to serve client requests. Calls to the service method within a given instance are serialized. EAServer creates multiple instances to minimize the time that clients have to wait for a blocked service request. EAServer calls the service method in an instance that is not already busy serving a previous request. If all available instances are busy, the request is delayed until a service call returns.

If multiple instances are created, calls to the service method are not necessarily serialized; service calls may occur simultaneously in different instances. If your service method changes static variables, you must add code to synchronize these changes or configure the servlet properties so that only one instance is created.

NoteImplementing the SingleThreadModel interface Your servlet class can implement the SingleThreadModel interface to indicate that calls to an instance’s service method must be serialized. Instances of these classes are always single-threaded by EAServer, regardless of whether the Single Threaded option is enabled.

Sessions settings

The Java Servlet API provides classes to create a session between a given HTTP client and servlets running on EAServer. You can use the session to record data related to the end-users session. If your servlet uses sessions, configure the following properties on the Sessions tab:

Java Classes settings

On the Java Classes tab, specify a list of additional Java classes that must be reloaded when you refresh the servlet. By default, EAServer reloads only the servlet implementation class. You can configure the classes to be custom loaded at the servlet, Web application, J2EE application, or server level. For more information, see Chapter 30, “Configuring Custom Java Class Lists.”

Additional Files settings

The Additional Files tab enables you to associate additional files with the servlet definition. If you synchronize the server where the servlet is installed, and elect to synchronize servlet files, these files will be transferred to the target servers. See Chapter 6, “Clusters and Synchronization,” in the EAServer System Administration Guide for more information on this feature.

You can specify the name of a Java class or package to be added to the archive, using the Java dot notation. For example, “com.sybase.CORBA” adds all files in the com.sybase.CORBA package.

Any other files must be separated by commas and specified relative to EAServer’s Repository subdirectory or with a full path. Full paths require that any server to which you synchronize share the same directory structure.

When you include additional files, you can either enter the file names individually, or you can use the Additional Files wizard to add multiple files, packages, classes, and directories.

To enter file names individually:

  1. Click Add. This opens the Add a File Name to the List dialog box.

  2. Enter the file name and click Ok.

To add multiple items:

  1. Click Additional Files Wizard. This open the Additional Files dialog box. Each item that you add is appended to the list.

  2. To add Java packages or classes:

    1. Click Browse

    2. Choose a *.class file and click Select.

    The class files must be deployed under EAServer’s java/classes directory.

  3. To add files or directories:

    1. Optionally, specify a file filter, such as *.txt.

    2. Optionally, select to use the JAGUAR environment variable.

    3. Click Browse.

    4. Choose a file or directory and click Select.

  4. To add property files from other entities:

    1. Click Browse.

    2. Choose a *.props file from under the Repository directory and click Select.

  5. To add file lists from other entities:

    1. Click Browse.

    2. Choose an entity’s *.files file and click Select.

  6. Click Add Files to Additional Files List.

Run As Identity

Configures an alternate identity used for authentication of component invocations from the servlet or JSP. By default, component invocations use the Web client’s identity. The settings are:

To enable use of the run-as identity for EJB component calls to remote servers, you must specify corbaname URLs in the EJB Reference properties for the Web application where the servlet is installed. For more information, see “Interoperable naming URLs” and “EJB references”.

Advanced settings

The Advanced tab allows you to edit property settings as they are stored in the EAServer configuration repository. You can only delete properties that you have added—you cannot delete default properties, such as the com.sybase.jaguar.servlet.name property. Repository property names are documented in Appendix B, “Repository Properties Reference,” in the EAServer System Administration Guide.

You can set properties as follows:

  1. Look for the property name in the list of properties. If it is displayed, highlight the property and click Modify. Otherwise, click Add.

  2. If adding the property, fill in the Add Property fields as follows:

  3. If modifying a property, edit the displayed value in the Modify Property window.

NoteWhen to use the Advanced tab Although you can use the Advanced tab to set any property prefixed with “com.sybase.jaguar.servlet,” Sybase recommends that you use this tab to set properties only as specified by the EAServer documentation or by Sybase Technical Support. Most properties can be configured graphically elsewhere in the EAServer Manager user interface.

Deploying and refreshing servlet classes

Deploying servlet classes

Although you can deploy servlet classes under any codebase that is specified in the CODEBASE environment variable, servlet classes should be deployed under EAServer’s java/classes subdirectory to simplify debugging. Only classes deployed under this codebase can be refreshed.

Refreshing servlets

The refresh feature is useful for debugging, since it allows you to load a changed version of the implementation class without restarting the server. If your implementation relies on other classes that must also be reloaded when the implementation is refreshed, specify them on the Java Classes tab in the Servlet Properties window. See “Java Classes settings”.

All servlets that are not installed in a Web application are considered to be part of the default Web application (EASDefault), and all servlets within the same Web application are refreshed at the same time.

To refresh all servlets in the Installed Servlets folder:

  1. Highlight the Servlets folder under the server icon where the servlet is installed.

  2. Choose File | Refresh.

  3. EAServer Manager will ask if you want to terminate any active requests. Choose Yes to refresh. If one of the servlets is servicing a request at this time, the client may receive partial data or an error. Choose No to cancel the refresh operation.

To refresh all the servlets in a Web application:

  1. Expand the server icon where the servlet is installed and highlight the Web application name under one of these folders:

  2. Choose File | Refresh.

  3. EAServer Manager will ask if you want to terminate any active requests. Choose Yes to refresh. If one of the servlets is servicing a request at this time, the client may receive partial data or an error. Choose No to cancel the refresh operation.

When you refresh a servlet, EAServer calls the servlet’s Servlet.destroy() method, reloads the implementation class and any classes specified on the Java Classes tab, and then calls the Servlet.init() method in the new instance.

Starting and stopping servlets

At times you may wish to stop and restart the servlet without reloading the class. Also, starting a servlet causes EAServer to load the implementation class if it has not already been loaded at startup or in response to a client request.

When you stop the servlet, EAServer calls the Servlet.destroy() method. When you start the servlet, EAServer calls the Servlet.init() method, unless it has already been called on the current instance of the implementation class.

To start a servlet:

  1. Expand the Servlets folder under the server icon where the servlet is installed. Highlight the servlet’s icon.

  2. Choose File | Start.

To stop a servlet:

  1. Expand the Servlets folder under the server icon where the servlet is installed. Highlight the servlet’s icon.

  2. Choose File | Stop.

  3. EAServer Manager will ask if you want to terminate any active requests. Choose Yes to stop the servlet. If the servlet is servicing a request when you stop the servlet, the client may receive partial data or an error.

Copyright © 2005. Sybase Inc. All rights reserved. Web application support