Servlets in WebObjects

Servlets are generic server extensions that expand the functionality of a Web server. By deploying WebObjects applications as servlets running inside servlet containers, you can take advantage of the features that your servlet container offers. Alternatively, you can deploy your applications using an HTTP adaptor that runs as a plug-in in your Web server. The adaptor forwards requests to your servlet container.

WebObjects applications can be deployed as servlets inside a servlet container such as Tomcat, WebLogic, or WebSphere. When an application runs as a servlet, instead of as a separate Java virtual machine (JVM) process, it runs inside the servlet container’s JVM, along with other applications. Note, however, that you can run only one instance of an application inside a servlet container. To run multiple instances of an application, you have to use multiple servlet containers. In addition, WebObjects deployment tools such as Monitor and wotaskd cannot be used with servlets.

To deploy an application as a servlet, you need to add the JavaWOJSPServlet framework to your project. When you build the project, Project Builder generates a WAR (Web application archive) file in addition to the WOA (WebObjects application) bundle. The WAR file has the appropriate classes and the web.xml file in the WEB-INF directory that your servlet container needs to launch the servlet. All you need to do in order to deploy the servlet is copy the WAR file to the application deployment directory of your servlet container. See Installing Servlets in WebSphere for special steps required to install servlets in WebSphere.

You may have to modify web.xml.template, specifically the %WOClassPath% marker, to ensure that the classpath to the application’s WOA bundle is correct. For WebLogic, the default Session class must be placed in a package because it conflicts with an internal WebLogic class. In general, all your classes should be inside packages.

The WAR file is not a complete application. WebObjects Deployment must be installed on the application host, as well as the application’s WOA bundle. However, using the Servlet Single Directory Deployment feature, you can deploy directories that contain all the necessary WebObjects classes. For more information, see Servlet Single Directory Deployment.

Developing a Servlet

This section shows you how to create a simple servlet using Project Builder.

Start by creating a WebObjects application project named Hello. You can deploy other types of WebObjects applications as servlets, such as Direct to Java Client, Direct to Web, Display Group, and Java Client.

In the Enable J2EE Integration pane of the Project Builder Assistant, select Deploy in a JSP/Servlet Container.

The “Deploy as a WAR file” option tells Project Builder to create a WAR file, which should be placed in your servlet container’s application directory. The WAR file contains all the files needed by an application except WebObjects frameworks. Therefore, WebObjects needs to be installed on the computer on which you want to deploy the application.

The “Deploy as a Servlet Single Directory Deployment” option tells Project Builder to include WebObjects frameworks in the WAR file. With this option, WebObjects does not need to be installed on the deployment computer.

The “Copy all JAR files into the application’s WEB-INF/lib directory” option tells Project Builder to copy framework and application JAR files to the WEB-INF/lib directory (necessary only when the servlet uses other servlets, or for JSPs that make use of actual objects).

As the right side of Figure 1-1 shows, the newly created project is, in all respects, a standard WebObjects application project. However, Project Builder adds the Servlet Resources folder to the Resources group. Anything you add to this folder is included in the WAR file or single deployment directory that Project Builder creates when you build the project, following the same directory structure. The Servlet Resources folder is a real directory in the project’s root directory; it’s shown on the left side of Figure 1-1.

Deploying a Servlet

The WEB-INF folder, under Server Resources, contains the web.xml.template file, which Project Builder uses to generate the servlet’s deployment descriptor. You can edit this template to customize the deployment descriptor for your deployment environment. There are several elements whose values are surrounded by percent (%) characters (these are placeholders that Project Builder evaluates when you build the project). These elements include cross-platform settings (see Cross-Platform Deployment for details). You can replace the placeholders with other values if your environment requires it.

Follow these steps to get to the JSP and servlet build settings in Project Builder:

1. Click the Targets tab, then click the Hello target in the Targets list. The Target pane appears. It contains the target settings list and a content pane.

2. Click Expert View under Settings in the target settings list to display the Hello target’s build settings in the content pane.

3. Locate the SERVLET_WEBAPPS_DIRbuild setting and enter the path of your servlet container’s application directory, as shown in Figure 1-2.

The SERVLET_COPY_JARS build setting tells Project Builder whether to copy framework and application JAR files to the WEB-INF/lib directory (necessary only when the servlet uses other servlets, or for JSPs that make use of actual objects).

The SERVLET_SINGLE_DIR_DEPLOYbuild setting indicates whether the application is to be deployed as a WAR file or a single deployment directory (see Servlet Single Directory Deployment for more information). Set it to NO to deploy as a WAR file and YES to deploy as a single deployment directory.

The SERVLET_SINGLE_DIR_DEPLOY_LICENSEbuild setting must contain your WebObjects Deployment license when SERVLET_SINGLE_DIR_DEPLOY is set to YES. If you don’t add your deployment license, you will not be able to build the application.

You can tell Project Builder where to put the WAR file by setting the value of the SERVLET_WEBAPPS_DIR build setting (this is especially convenient during development). By default, WAR files are placed in the build directory of your project.

Project Builder WO (on Windows) adds two buckets to your project: JSP Servlet WEB-INF and JSP Servlet Resources. The JSP Servlet WEB-INF bucket is a holding place for JAR files, classes, and TLD files (which are auto-routed to the correct subdirectories in the WEB-INF directory of the generated WAR file or single deployment directory—lib, class, and tld respectively; the web.xml.template file is also located here). The JSP Servlet Resources bucket contains any other items you want to add to the WAR file or single deployment directory (you can drag files and folders into this bucket; Project Builder WO preserves the directory structure when it generates the WAR file). These items are not auto-routed.

There are also several new variables defined in Makefile.preamble. The SERVLET_APP_MODE variable indicates whether Web server resources are loaded from the WOA bundle (the default) or the servlet container (by setting it to "Deployment". The SERVLET_WEBAPPS_DIR, SERVLET_COPY_JARS, SERVLET_SINGLE_DIR_DEPLOY, and SERVLET_SINGLE_DIR_DEPLOY_LICENSE variables perform the same function described for Project Builder’s servlet-related build settings earlier.

This is how you set up the SERVLET_WEBAPPS_DIR variable in Project Builder WO:

export SERVLET_WEBAPPS_DIR = C:\Tomcat\webapps

You can test the servlet by setting the SERVLET_WEBAPPS_DIR build setting to the path of your servlet container’s application deployment directory and building the project. Before you build, you can edit Main.wo using WebObjects Builder to add a message to the page, such as Hello. I’m a servlet. When Project Builder finishes building the application, it places the Hello.war file in your servlet container’s application deployment directory. The contents of the Hello.war file are shown in Listing 1-1.

Listing 1-1  Contents of Hello.war file

Hello/

    META-INF/

        MANIFEST.MF

    WEB-INF/

        classes/

        lib/

            JavaWOJSPServlet_client.jar

        tlds/

            WOtaglib_1_0.tld

        web.xml

After restarting your servlet container you can connect to the Hello application through a Web browser. By default, the connection URL is

http://host:port/AppName/WebObjects/AppName.woa

where host is the computer where the servlet container is running and port is the port the container runs on. Table 1-1 lists the default host and port for Tomcat, WebLogic, and WebSphere.

Adding Servlet Support to an Existing Application

To add servlet support to an existing application, all you need to do is add the JavaWOJSPServlet framework to your project and rebuild it. On Mac OS X, follow these steps:

1. Open the project you want to add servlet support to in Project Builder.

2. Add the JavaWOJSPServlet framework.

   1. Select the Frameworks group from the Files list.

   2. Choose Project > Add Frameworks.

      A sheet appears with the Frameworks folder selected.

   3. Select JavaWOJSPServlet.framework from the file list, and click Open.

   4. Select Application Server from the target list, and click Add.

      Notice that the Servlet Resources folder is added to the Resources group.

3. Build the project using the Deployment build style.

4. Copy the WAR file or deployment directory in the build directory of your project to the application deployment directory of your servlet container.

   You can avoid this step by setting SERVLET_WEBAPPS_DIR to the path of your servlet container’s application deployment directory. When using SSDD, you have to add your WebObjects Deployment license number to the project, as explained in Deploying a Servlet.

5. If necessary, restart your servlet container.

The servlet should now be available through your servlet container.

On Windows, follow these steps:

1. Open the project you want to add servlet support to in Project Builder WO.

2. Add the JavaWOJSPServlet framework.

   1. Select the Frameworks bucket.

   2. Choose Project > Add Files.

   3. If necessary, navigate to the \Apple\Library\Frameworks directory (the directory should be selected by default).

   4. Select JavaWOJSPServlet.framework from the file list and click Open.

   5. Add the servlet-support variables to the Makefile.preamble file. One way to do this is by creating a new project with servlet support and copying its servlet-related variables to the Makefile.preamble in the project you’re modifying.

3. Rebuild the project.

4. If necessary, copy the WAR file or single deployment directory in the project’s build directory to the application deployment directory of your servlet container. On Windows, the WAR file or single deployment directory is located at the top level of the project’s directory.

5. If necessary, restart your servlet container.

Servlet Single Directory Deployment

As mentioned earlier, Servlet Single Directory Deployment (SSDD) allows you to create an application directory that you can deploy on a computer on which WebObjects is not installed.

To deploy an application using SSDD, do the following:

1. Set the SERVLET_SINGLE_DIRECTORY_DEPLOY build setting to YES.

2. Enter your WebObjects Deployment license as the value of the SERVLET_SINGLE_DIRECTORY_DEPLOY_LICENSE build setting.

When you build the application, Project Builder creates a directory named after the project. Listing 1-2 lists the contents of the Hello deployment directory.

Listing 1-2  Contents of the Hello single deployment directory

Hello/

    WEB-INF/

        classes/

        Extensions// 1

        Hello.woa

        lib/

            JavaWOJSPServlet_client.jar

        Library// 2

            Frameworks/

        LICENSE// 3

        tlds/

            WOtaglib_1_0.tld

        web.xml

The following list explains the numbered items in Listing 1-2.

1. The Extensions directory contains the JAR files in /Library/WebObjects/Extensions.

2. The Library directory contains the frameworks in the Frameworks group of the Files list of the project.

3. The LICENSE file contains the WebObjects Deployment license agreement.

Cross-Platform Deployment

To support cross-platform deployment, WebObjects uses three variables that tell the servlet container at runtime where to find WebObjects frameworks (directories with the .framework extension) and the WOA bundles (bundles with the extension .woa):

• WOROOT indicates the path where WebObjects frameworks are installed. On Mac OS X, for example, WebObjects frameworks are located in the /System/Library/Frameworks directory and WOROOT is set to /System. On Windows, WOROOT could be set to C:\Apple, and on Solaris it may be /opt/Apple.

• LOCALROOT indicates the path where local frameworks are installed. On Mac OS X, these frameworks are located in the /Library/Frameworks directory, and LOCALROOT is set to /. On Windows, LOCALROOT may be set to C:\Apple\Local, while on Solaris it could be /opt/Apple/Local.

• WOAINSTALLROOT specifies the location of WOA bundles. On Mac OS X, the default is /Library/WebObjects/Applications.

When you deploy the WAR file of your servlet on a computer where the framework and WOA files are in different locations from the default ones, you can specify the correct paths using the variables described above. You can accomplish this in two ways:

• configuring the application’s deployment descriptor

• configuring the servlet container

<web-app>

    <context-param>

        <param-name>WOROOT</param-name>

        <param-value>C:\WebObjectsFrameworks</param-value>

    </context-param>

    <context-param>

        <param-name>LOCALROOT</param-name>

        <param-value>C:\Apple\Local</param-value>

    </context-param>

    <context-param>

        <param-name>WOAINSTALLROOT</param-name>

        <param-value>C:\WebObjectsApplications</param-value>

    </context-param>

    ...

</web-app>

mkdir filename

jar -xvf filename.war

jar -cvf fileName.war .

#! /bin/sh

...

$JAVACMD $TOMCAT_OPTS -DWOROOT=/System -DLOCALROOT=/

-DWOAINSTALLROOT=/Library/WebObjects/Applications

-Dtomcat.home=${TOMCAT_HOME}  org.apache.tomcat.startup.Tomcat "$@" &

BASEDIR='dirname $0'

$BASEDIR/tomcat.sh start "$@"

"${JAVA_HOME}/bin/java" ${JAVA_VM} ${MEM_ARGS}

-classpath ${CLASSPATH}"

-Dweblogic.Name=myserver

-Dbea.home="/opt/bea"

"-DWOROOT=/opt/Apple"

"-DLOCALROOT=/opt/Apple/Local"

"-DWOAINSTALLROOT=/applications/production"

-Dweblogic.management.username=${WLS_USER}

-Dweblogic.management.password=${WLS_PW}

-Dweblogic.ProductionModeEnabled=${STARTMODE}

-Djava.security.policy="${WL_HOME}/server/lib/weblogic.policy"

weblogic.Server

% export TOMCAT_OPTS="-DWOROOT=/System -DWOAINSTALLROOT=/WebObjects/Applications -DLOCALROOT=/"

% setenv TOMCAT_OPTS "-DWOROOT=/System -DWOAINSTALLROOT=/WebObjects/Applications -DLOCALROOT=/"

Installing Servlets in WebSphere

To install a single deployment directory you need to create a WAR file from the directory. Execute the following commands to create the WAR file:

cd <path-to-project>/AppName

jar -cvf AppName.war .

To install a WAR file, perform these steps using console:

1. Choose Nodes > Server > Enterprise Apps > Install.

2. Navigate to the WAR file’s location.

3. Enter the application’s name in the App Name text input field; for example, MyApp.

4. Enter the context name for the application in the Context Root text input field; for example, /MyApp.