Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Servlets
Servlet technology was developed as an improvement over CGI. It’s an open standard that can be freely adopted by any vendor. It provides an infrastructure that allows applications from different manufacturers to cooperate and share resources.
The following sections explain how you can take advantage of servlet technology in WebObjects:
Servlets in WebObjects provides an overview of servlet technology as it is implemented in WebObjects.
Developing a Servlet guides you through creating a simple servlet.
Deploying a Servlet explores deployment issues and tasks you need to keep in mind when deploying a servlet.
Adding Servlet Support to an Existing Application explains how to add servlet support to an existing WebObjects application.
Servlet Single Directory Deployment describes the feature that allows you to create a directory containing the files necessary to deploy an application as a servlet that does not require WebObjects to be installed on the deployment computer.
Cross-Platform Deployment shows you how to simplify cross-platform deployment (or deployment in a platform other than the development platform) by allowing you to easily define the paths your servlet container uses to locate WebObjects frameworks, local frameworks, and WebObjects application bundles—WebObjects application (WOA) directories.
Installing Servlets in WebSphere addresses special issues when installing WAR files in WebSphere.
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:
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.
Click Expert View under Settings in the target settings list to display the Hello target’s build settings in the content pane.
Locate the
SERVLET_WEBAPPS_DIR
build 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_DEPLOY
build 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_LICENSE
build 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.
Container | Host | Port |
---|---|---|
Tomcat |
|
|
WebLogic |
|
|
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:
Open the project you want to add servlet support to in Project Builder.
Add the JavaWOJSPServlet framework.
Select the Frameworks group from the Files list.
Choose Project > Add Frameworks.
A sheet appears with the Frameworks folder selected.
Select JavaWOJSPServlet.framework from the file list, and click Open.
Select Application Server from the target list, and click Add.
Notice that the Servlet Resources folder is added to the Resources group.
Build the project using the Deployment build style.
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.If necessary, restart your servlet container.
The servlet should now be available through your servlet container.
On Windows, follow these steps:
Open the project you want to add servlet support to in Project Builder WO.
Add the JavaWOJSPServlet framework.
Select the Frameworks bucket.
Choose Project > Add Files.
If necessary, navigate to the
\Apple\Library\Frameworks
directory (the directory should be selected by default).Select
JavaWOJSPServlet.framework
from the file list and click Open.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 theMakefile.preamble
in the project you’re modifying.
Rebuild the project.
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.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:
Set the
SERVLET_SINGLE_DIRECTORY_DEPLOY
build setting toYES
.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.
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 andWOROOT
is set to/System
. On Windows,WOROOT
could be set toC:\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, andLOCALROOT
is set to/
. On Windows,LOCALROOT
may be set toC:\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
Configuring the Deployment Descriptor
The deployment descriptor of a servlet is the web.xml
file, located in the WEB-INF
directory of the WAR file. This file is generated from the web.xml.template
file in your project.
To configure your application’s deployment descriptor during development, you edit the web.xml.template
file. Alternatively, you can edit the web.xml
file of the WAR file (after expanding the WAR file). Locate the <param-name>
tags for the appropriate variables, and set the value for their corresponding <param-value>
tag.
This is an example of a web.xml.template
file on Windows:
<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> |
You expand the WAR file by executing the following commands in your shell editor:
mkdir filename |
jar -xvf filename.war |
When you’re done editing the web.xml
file, you re-create the WAR file by executing
jar -cvf fileName.war . |
Configuring the Servlet Container
This method allows your settings to be propagated to all applications and it overrides the values set in the deployment descriptor. Using this approach, you can deploy WebObjects applications without worrying about each application’s configuration. You can configure the servlet container in two ways:
editing the launch script of the servlet container
defining environment variables
This is an example of the launch script in Tomcat (startup.sh
):
#! /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 "$@" |
This is an example of the launch-script format in WebLogic (startWLS.sh
):
"${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 |
This is how you would define environment variables using the bash or zsh shell editors:
% export TOMCAT_OPTS="-DWOROOT=/System -DWOAINSTALLROOT=/WebObjects/Applications -DLOCALROOT=/" |
And this is how you would do it using the csh shell editor:
% 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
:
Copyright © 2002, 2005 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2005-08-11