One of the important ways that developers can take advantage of JavaBean^TM technology is to create and use servlets that are themselves beans. Servlets that are beans offer two distinct advantages:

• If the servlet is a bean, any changes to its configuration take effect immediately.
• The persistant state of the servlet bean, as well as its configuration, can be stored as a serialized file. For example, if the servlet bean manages a counter, the state of the counter can be made persistant through the Java serialization mechanism. Thus, if you stop and restart the server, the counter would retain its latest value.

Another important way that developers can take advantage of JavaBean technology is to use JavaBeans in servlets and JHTML files. For more information on this topic, see Using JavaBeans in Servlets and JHTML Files.

This document contains these sections which describe how to install, administer, and invoke servlet beans.

• Introduction
• Servlet Bean Instantiaton
• Servlet Bean Properties
  • Passing Properties to Servlet Beans
• Servlet Bean Installation
  • Installing Configured Servlet Beans
  • Installing Unconfigured Servlet Beans
• Invoking Servlet Beans

A servlet bean is a servlet that adheres to the JavaBeans design pattern for getting and setting properties. This pattern defines a standard method/class combination for getting and setting properties, and uses mandatory type signatures and naming conventions. The design pattern for read/write properties is:

              void setFoo(Xyz x);  
              Xyz getFoo();
          

The JavaServer assumes that all servlets are beans. The server sets all of the servlet bean properties (passed to the servlet as initial arguments) by using JavaBean introspection.

Servlet beans can be distributed as

• class files
• serialized files ("servlet_name.ser" files)
• class and/or serialized files in JAR archive format

Servlet beans can be serialized into .ser files. A serialized file can be thought of as an instance of the class. The serialized servlet bean files and the class file they reference can be packaged together in a JAR file. JAR files are also refered to as installed files.

Serialized servlet bean files and the class file they reference can also reside outside of a JAR file. These files are refered to as not installed or dropped-in files.

The distinction between installed files and dropped-in files is that you cannot use the JavaServer Adminstration Tool to change the initial arguments specified in the dropped-in serialized server bean files (dropped-in serialized files are read-only). Nor can you use the Tool to create serialized files for dropped-in class files. Instead, you use the Tool to specify properties and initial values for the dropped-in files.

NOTE: All references to servlet bean files in this document refer to installed files. This document does not describe dropped-in files unless they are mentioned specifically.

Servlet Bean Instantiaton

The server provides support for instantiating servlet beans by providing a classloader that deserializes the server beans files from .ser files. These .ser files can be dropped-in files or reside in a JAR file. When a JAR or dropped-in file changes on disk, the classloader automatically reloads it.

Servlet beans files can reside in any of these directories:

• servlet/ directory
• servletbeans/ directory
• any directory included in the CLASSPATH

To take advantage of the automatic reloading feature of the JavaServer, we suggest that you store your servlet beans files (class, .ser, and .jar files) in the servletbeans/ directory and not include it in the CLASSPATH. (Automatic reloading is not performed on files residing in directories in the CLASSPATH.)

Servlet Bean Properties

Properties are the initial arguments which are passed to a servlet bean. For example, for a servlet bean named "Counter", there could be an initial argument initial=0. Similarly, for a servlet bean named "CGI" there could be an initial argument bindir=cgi-bin.

Passing Properties to Servlet Beans

Properties are passed to the servlet bean by:

• using the ServletConfig interface. The server always passes properties with this interface.
• calling the set methods for the property by using JavaBeans introspection.

Using the ServerConfig Interface

Properties are passed to the servlet bean by the ServerConfig interface when the init method of the Servlet interface is called. The init method is called by network service when it loads the servlet.

Calling Set Methods for the Property

Properties can also be passed to the servlet bean by calling set methods for the corresponding property. For example, the following code snippet sets the value for the argument PropertyName:

      void setPropertyName (String);
      

This method will be called for every property which you set by using the Administration Tool. After the servlet is loaded, if you use the Tool to change properties, this method will be called with a new value.

Servlet Bean Installation

• installing configured servlet beans
• installing servlet beans which are not configured

If your servlet bean is configured (that is, if it has a .ser file that contains initial arguments), move the servlet bean file into the appropriate directory. Usually, this will be the servletbeans/ directory. If the directory is not on the CLASSPATH, the server will automatically reload the servlet.

NOTE: If your servlet is a class file or a .ser file, you will not be able to use the Administration Tool to change any of the servlet bean's properties. You can use the Tool to change the properties of only those servlets that are contained in .jar files.

Installing Unconfigured Servlet Beans

If your servlet bean is not configured, use the Administration Tool to specify initial arguments for it.

1. Invoke the Administration Tool.
2. Click Web Service, then click the Manage button.
3. In the Web Service dialog, click the Servlets icon.

   

4. Click the Add branch of the tree and enter the following information for the servlet:
   • Servlet Name - Enter the unique name of the servlet you are adding.
   • Servlet Class - The name of the Java class for the servlet. This consists of the package name without the .class extension. For example, sun.server.http.FileServlet is a valid class name.
5. Click the Bean Servlet: "Yes" radio button and enter a name for the .jar file that will contain the servlet bean.
6. Click the Add button. The Administration Tool displays the Configuration and Properties tabs.

   

7. Enter the following information for the servlet:
   • Description - A text string describing the servlet. This field is sometimes blank.
   • Class Name - The name of the associated class file for the servlet.
   • Load at Startup - Whether the Java Web Server loads the servlet when the server starts.
   • Loaded Now - Whether the servlet is currently loaded.
   • Load Remotely - Whether the Java Web Server loads the servlet from a remote location.
   • Class File URL - The URL that points to the class file for the remote servlet.
8. Click Save, then click the Properties tab.

   

9. Enter the initial arguments for the properties in the Value field.
10. Click the Add button, then click the Save button to save your changes to the Java Web Server.

After the servlet bean is loaded, you can invoke it in the same way as you would invoke any other servlet:

• call the servlet bean directly by using a URL
• embed the servlet bean in a server-side include statement inside an HTML document
• invoke an alias for the servlet bean

Servlet bean files can be invoked by calling them as a URL address. Note that even though you installed the servlet bean in the servletbeans/ directory, you call it with a servlet/ URL. The server will search the servletbeans/ directory for the appropriate file.

http://<host_name>:< port >/servlet/<ServletName>

ServletName can represent either the name of a servlet bean class file or a .ser file. You invoke a class file or a serialized file with the name of the file without the .class or .ser extension. You can do this regardless of whether the file resides in a directory "as is" (that is, it is a dropped-in file), or it resides in a JAR file.

For example, a servletbeans/ directory contains the files Counter.class, counter1.ser, and a JAR file Hello.jar. The JAR file contains the files Hello.class, hello1.ser, and hello2.ser.

The following table describes how to invoke various servlet beans files.

To Invoke this Servlet Bean File	Use this URL Address
serialized file in the servletbeans/ directory	Use the file name without the .ser extension. For example: http://host:port/servlet/counter1
serialized file in a .jar file in the servletbeans/ directory	Use the file name without the .ser extension. For example: http://host:port/servlet/hello1
class file in the servletbeans/ directory	Use the file name without the .class extension. For example: http://host:port/servlet/Counter
class file in a .jar file in the servletbeans/ directory	Use the file name without the .class extension. For example: http://host:port/servlet/Hello

An Example

The servlet Hello.class creates a web page with a greeting. A code snippet from Hello.class appears below.

     String greeting = "Hello World"
     
     //code to get, set, and display greetings
         Public String getString {
             return greeting;
         }
           Public void setSrting(String g){
             greeting = g;
         }
     public void doGet (HttpServletRequest req, HttpServletResponse res)
          throws ServletException, IOException
    {
	PrintWriter		out;

	res.setContentType("text/html");
	out = res.getWriter();

	out.println("< html >");
	out.println("< head >< title >Greeting < /title >< /head >");
	out.println("< body >");
	out.println("< h1 >" + getGreeting() + "< /h1 >");
	out.println("< /body > < /html >");
    }
     

There are also two .ser files, hello1.ser and hello2.ser, which contain alternate greetings for the servlet. These three files, Hello.class, hello1.ser, and hello2.ser are archived as a .jar file and stored in the servletbeans/ directory.

The hello1.ser file contains the initial argument Greeting="Good Morning" and hello2.ser contains the initial argument Greeting="Good Evening".

The invocation http://server_root /servlet/hello1 returns "Good Morning"
The invocation http://server_root /servlet/hello2 returns "Good Evening"
The invocation http://server_root /servlet/Hello returns "Hello World"

Embedding Servlet Beans in a Server-side Include Statement

You can invoke a servlet bean by embedding it in a server-side include statement inside an HTML document. For example, in an .shtml file, you can add a server side include with this statement:

< servlet name="servletAliasName" code=ServletBeanExample > < /servlet >

In this example, name="servletAliasName" represents an alias for the servlet bean and code=ServletBeanExample represents the name of the servlet class. Note that the code value can be omitted if an alias has been created for the servlet bean with the Administration Tool.

Invoking an Alias for the Servlet Bean

You can use the Servlet Aliases page of the Administration Tool to create an alias for the servlet bean. The Servlet Aliases page lets you specify the pathname mapping rules that the JavaServer uses to invoke servlets. These rules allow you to use a shortcut URL to call a servlet from your browser, or to embed the shortcut within HTML documents (using server-side includes), or within other Java programs.

For more information, see Servlet Aliases

Top java-server-feedback@java.sun.com

Copyright © 1997 Sun Microsystems, Inc. All Rights Reserved.