Sun Java System Web Server 6.1 SP12 Administrator's Guide

Java Servlets and JavaServer Pages (JSP)

This section discusses how to install and use Java Servlets and JavaServer Pages on Sun Java System Web Server.

The following topics are described:

Overview of Servlets and JavaServer Pages

Sun Java System Web Server 6.1 supports the Servlet 2.3 API specification, which allows servlets and JSPs to be included in web applications.

A web application is a collection of servlets, JavaServer Pages, HTML documents, and other web resources which might include image files, compressed archives, and other data. A web application may be packaged into an archive (a WAR file) or exist in an open directory structure.

Note –

Servlet API version 2.3 is fully backward compatible with version 2.1, so all existing servlets will continue to work without modification or recompilation.

To develop servlets, use Sun Microsystems’ Java Servlet API. For information about using the Java Servlet API, see

http://java.sun.com/products/servlet/index.jsp

A JSP is a page, much like an HTML page, that can be viewed in a web browser. However, in addition to HTML tags, it can include a set of JSP tags and directives intermixed with Java code that extend the ability of the web page designer to incorporate dynamic content in a page. These additional features provide functionality such as displaying property values and using simple conditionals. Sun Java System Web Server 6.1 supports the JavaServer Pages (JSP) 1.2 API specification.

Note –

Ensure that the case of the URI your application requests for (for example, /foo.JSP) matches the canonical case of the file system path (for example, C:\Program Files\WebServer\docs\foo.jsp). This is necessary because the Sun Java System Web Server 6.1 Java web container currently performs case-sensitive pattern matches.

For information about creating JSPs, see Sun Microsystem’s JavaServer Pages web site at:

http://java.sun.com/products/jsp/index.jsp

For information about developing servlets and JSPs for use with Sun Java System Web Server, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

What the Server Needs to Run Servlets

Sun Java System Web Server includes the JDK version 1.4.1_03. While in previous versions of the Web server, Java was configured server-wide, in the 6.1 release, you can configure Java per instance of the Web server.

You may use the JDK that is bundled with Sun Java System Web Server 6.1 or you may use a JDK of your choice, in which case you must specify a path to the JDK. For more information on how you can do this, see Configuring JVM Settings.

By default, Java is disabled when you install the Sun Java System Web Server. In order to enable servlets, you must first enable Java.

For information on how you can enable Java, see Enabling and Disabling Java.

Deploying Web Applications

The following sections describe how to deploy, edit, and delete web applications either manually by using the wdeploy command line utility, or through the user interface.

Using the server.xml File

Once deployed, your web applications are enabled by default. To disable a deployed web application manually you would need to modify the server.xml file as follows:

<VS>
<WEBAPP uri="/mywebapp" path="/webappdir" enabled = "false" >
</WEBAPP>
...
</VS>

If you inadvertently deploy or edit more than one web application with the same description, and one of them is disabled, the server will ignore enabled = “false” and continue with default setting of enabled = “true”.

For more information about the server.xml file, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

You can deploy and edit web applications in two ways:

Using the Administration Server Interface

Using Sun Java System Web Server 6.1, you can deploy, edit, delete, disable, and enable web applications for a specified virtual server.

Deploying Web Applications

You can access the Deploy Web Applications page by selecting Deploy Web Applications under the Web Applications tab of the Virtual Server Manager.

To deploy a web application, perform the following steps.

To deploy a web application

Select Local Machine or Server Machine from the WAR File On drop-down list.

Select Local Machine when uploading a WAR file to your server. Select Server Machine when the WAR file already resides there.

Enter the path on the local or server machine to the WAR file containing the web application in the field provided.

On server machines enter the absolute path to the WAR file.

On local machines you can browse the available paths. Clicking browse bring up the File Upload window, allowing you to select the WAR file to upload to your server.

Enter the URI on the virtual server for the web application in the field provided.

Enter the absolute path to the directory on the server machine into which the contents of the WAR file will be extracted. If the directory does not exist, one will be created.

Click OK.

Click Apply.

Select Dynamic Reconfiguration for your web application to be deployed.

Editing Web Applications

You can edit, delete, disable, or enable an already deployed web application. Access the Edit Web Applications page by selecting Edit Web Applications under the Web Applications tab of the Virtual Server Manager.

To edit, delete, disable, or enable an already deployed web application, follow these steps

To edit, delete, disable, or enable an already deployed web application

Select the action you wish to perform from the drop-down list in the Action column next to the web application you are editing. Choose:
- Edit to change the URI where the web application can be accessed.
- Delete to delete the web application entry from the web applications file and delete the directory where the application is deployed.
- Disable to make the web application inaccessible from the URI, but not delete it.
- Enable to reactivate web applications that were previously disabled.
Caution –
Deleting a web application also deletes the directory the application is deployed in.

(Optional) Enter a new URI in the URI field if you are editing the web application.

Click OK.

Click Apply.

Select Dynamic Reconfiguration for your web application to be deployed.

Using the Command Line Interface

Before you can deploy a web application manually, you must make sure that the server_root/bin/https/httpsadmin/bin directory is in your path and that the IWS_SERVER_HOME environment variable is set to your server_root directory.

To deploy a virtual server web application:

You can use the wdeploy utility at the command line to deploy a WAR file into a virtual server web application environment:

wdeploy deploy -u <uri_path> -i <instance> -v 
<vs_id> [ [-V <verboseLevel>]| [-q] ] [-n] [-d <directory>]
 <war_file>

To delete a virtual server web application:

wdeploy delete -u <uri_path> -i <instance> -v 
<vs_id> [ [-V <verboseLevel>] | [-q] ] [-n] hard|soft

To list the web application URIs and directories for a virtual server:

wdeploy list -i <instance> -v <vs_id> [ [-V <verboseLevel>] | [ -q] ]

The command parameters have the following meanings:

`uri_path`	The URI prefix for the web application.
`instance`	The server instance name.
`vs_id`	The virtual server ID.
`directory`	(optional) The directory to which the application is deployed, or from which the application is deleted. If not specified for deployment, the application is deployed to the document root directory.
`hard \| soft`	Specifies whether the directory and the `server.xml` entry are deleted (`hard`) or just the `server.xml` entry is deleted (`soft`).
`war_file`	The WAR file name
verboseLevel	The verbose level to display the log messages on console. The value can range from 0 to 4. The default value is 1. Note that in Sun Java System web Server 6.1, the `loglevel` attribute of the `LOG` element in `server.xml` is used in lieu of this element.
`-q`	(quiet) Sets the verbose level to zero. It is equivalent to the setting `-V 0`.
`-n`	prevents `wdeploy` from automatically sending the reconfigure command to the web server. For more information, see Using -n in the wdeploy Command.

Caution –

If you deploy a web application and do not specify a directory, the application is deployed to the document root directory. If you then delete the application using the hard parameter, the document root directory will be deleted.

When you execute the wdeploy deploy command, three things happen:

A web application with the given uri_path and directory gets added to the server.xml file.
The WAR file gets extracted at the target directory.
The server is dynamically reconfigured to load the new web application.

For example:

wdeploy deploy -u /hello -i server.sun.com -v acme.com 
-d /s1ws61/https-server.sun.com/acme.com/web-apps/hello 
/s1ws61/plugins/servlets/examples/web-apps/HelloWorld/
HelloWorld.war

This utility results in the following server.xml entry:

<VS>
    <WEBAPP uri="/hello"
     dir="/s1ws61/https-server.sun.com/acme.com/webapps/hello">
</VS>

The /s1ws61/https-server.sun.com/acme.com/web-apps/hello directory has the following contents:

colors
index.jsp
 META-INF
WEB-INF/
     web.xml
     /classes/
         HelloWorldServlet.class
         HelloWorldServlet.java
         SnoopServlet.class
         SnoopServlet.java

Using -n in the wdeploy Command

In Sun Java System Web Server 6.1, after deploying or deleting a web application, wdeploy dynamically reconfigures the server, causing the server to load or unload the web application that was deployed or deleted. Previously, you had to explicitly reconfigure the server in order for your changes to take effect by doing one of the following:

Using the reconfig script
Restarting the server
Clicking the Apply link in the Administration User Interface.

Now a successful wdeploy command will automatically be enabled to service requests for a new web application, or to stop servicing requests for a deleted web application.

The -n option prevents wdeploy from automatically sending the reconfigure command to the web server. Use the -n option in your command when deploying or undeploying multiple web applications (in a script for example), and you want to reconfigure the server only once after the last web application is deployed.

Accessing Deployed Web Applications

After you have deployed an application, you can access it from a browser as follows:

http://vs_urlhost[:vs_port]/uri_path/[index_page]

The parts of the URL have the following meanings:

`vs_urlhost`	One of the `urlhosts` values for the virtual server.
`vs_port`	(optional) Only needed if the virtual server uses a non-default port.
`uri_path`	The same one you used to deploy the application. This is also the context path.
`index_page`	(optional) The page in the application that end users are meant to access first.

For example:

http://acme.com:80/hello/index.jsp

or:

http://acme.com/hello/

Return Values

The wdeploy option returns following exit values:

0: Indicates that the wdeploy option was executed successfully.
1: Indicates that an error occurred while executing the wdeploy option due to invalid command line arguments or invalid content of the configuration files.
2: Indicates that the error is due to operating system settings. Either the specified directory doesn’t exist or the file permission is not set.

Deploying Servlets and JSPs Not in Web Applications

You can deploy 4.x servlets and JSPs outside of web applications, but only in the default virtual server. For information, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

Configuring JVM Settings

You can configure attributes for the Java Virtual Machine (JVM) in the Java tab in the Server Manager.

For more information on these options, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

Deleting Version Files

The Delete Version Files page on the Java tab of the Server Manager allows you to delete the files that contain the version numbers for the JavaServer Pages class cache and the session data cache. This page has the following fields:

Clear Session Data

Deletes the SessionData directory, which stores persistent session information if the server uses the MMapSessionManager session manager.

Delete JSP ClassCache Files

Deletes the ClassCache directory, which caches information for JavaServer Pages (JSP). The default location of this directory is:

server_root/https-server_id/ClassCache/virtual_server_id/webapp_uri/

When the server serves a JSP page, it creates a .java and a .class file associated with the JSP and stores them in the JSP class cache under the ClassCache directory.

The server uses two directories to cache information for JSP and servlets:

ClassCache

The server uses the following directory to cache information for JavaServer Pages (JSP):

server_root/https-server_id/ClassCache/virtual_server_id/webapp_uri/

When the server serves a JSP page, it creates a .java and a .class file associated with the JSP and stores them in the JSP class cache under the ClassCache directory.
SessionData

If the server uses the MMappedSessionManager session manager, it stores persistent session information in the SessionData directory.

When the server starts up, if it does not find the version files, it deletes the directory structure for the corresponding caches and re-creates the version files. Next time the server serves a JSP page, it recreates the JSP class cache. The next time the server serves a JSP page or servlet while using MMappedSessionManager session manager, it recreates the session data cache.

If a future upgrade of the server uses a different format for the caches, the server will check the number in the version file and clean up the caches if the version number is not correct.