test

Oracle GlassFish Server 3.0.1 Application Development Guide

Chapter 8 Developing Web Applications

This chapter describes how web applications are supported in the Oracle GlassFishTM Server and includes the following sections:

For general information about web applications, see Part II, The Web Tier, in The Java EE 6 Tutorial.

Note –

The Web Profile of the GlassFish Server supports the EJB 3.1 Lite specification, which allows enterprise beans within web applications, among other features. The full GlassFish Server supports the entire EJB 3.1 specification. For details, see JSR 318.

Using Servlets

GlassFish Server supports the Java Servlet Specification version 3.0.

Note –

Servlet API version 3.0 is fully backward compatible with versions 2.3, 2.4, and 2.5, so all existing servlets should work without modification or recompilation.

To develop servlets, use the Java Servlet API. For information about using the Java Servlet API, see the documentation at http://java.sun.com/products/servlet/index.jsp.

The GlassFish Server provides the wscompile and wsdeploy tools to help you implement a web service endpoint as a servlet. For more information about these tools, see the Oracle GlassFish Server 3.0.1 Reference Manual.

This section describes how to create effective servlets to control application interactions running on a GlassFish Server, including standard-based servlets. In addition, this section describes the GlassFish Server features to use to augment the standards.

This section contains the following topics:

Caching Servlet Results

The GlassFish Server can cache the results of invoking a servlet, a JSP, or any URL pattern to make subsequent invocations of the same servlet, JSP, or URL pattern faster. The GlassFish Server caches the request results for a specific amount of time. In this way, if another data call occurs, the GlassFish Server can return the cached data instead of performing the operation again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set the cache to expire after 300 seconds.

Whether to cache results and how to cache them depends on the data involved. For example, it makes no sense to cache the results of a quiz submission, because the input to the servlet is different each time. However, it makes sense to cache a high level report showing demographic data taken from quiz results that is updated once an hour.

To define how a GlassFish Server web application handles response caching, you edit specific fields in the sun-web.xml file.

Note –

A servlet that uses caching is not portable.

For Javadoc tool pages relevant to caching servlet results, go to https://glassfish.dev.java.net/nonav/docs/v3/api/ and click on the com.sun.appserv.web.cache package.

For information about JSP caching, see JSP Caching.

The rest of this section covers the following topics:

Caching Features

The GlassFish Server has the following web application response caching capabilities:

Default Cache Configuration

If you enable caching but do not provide any special configuration for a servlet or JSP, the default cache configuration is as follows:

Caching Example

Here is an example cache element in the sun-web.xml file:

<cache max-capacity="8192" timeout="60">
<cache-helper name="myHelper" class-name="MyCacheHelper"/>
<cache-mapping>
	<servlet-name>myservlet</servlet-name>
	<timeout name="timefield">120</timeout>
	<http-method>GET</http-method>
	<http-method>POST</http-method>
</cache-mapping>
<cache-mapping>
	<url-pattern> /catalog/* </url-pattern>
	<!-- cache the best selling category; cache the responses to
	   -- this resource only when the given parameters exist. Cache
	   -- only when the catalog parameter has 'lilies' or 'roses'
	   -- but no other catalog varieties:
	  -- /orchard/catalog?best&category='lilies'
	  -- /orchard/catalog?best&category='roses'
	  -- but not the result of
	   -- /orchard/catalog?best&category='wild'
	-->
	<constraint-field name='best' scope='request.parameter'/>
	<constraint-field name='category' scope='request.parameter'>
		<value> roses </value>
		<value> lilies </value>
	</constraint-field>
	 <!-- Specify that a particular field is of given range but the
	   -- field doesn't need to be present in all the requests -->
	<constraint-field name='SKUnum' scope='request.parameter'>
		<value match-expr='in-range'> 1000 - 2000 </value>
	</constraint-field>
	<!-- cache when the category matches with any value other than
	   -- a specific value -->
	<constraint-field name="category" scope="request.parameter>
		<value match-expr="equals" cache-on-match-failure="true">
       bogus
		</value>
	</constraint-field>
</cache-mapping>
<cache-mapping>
	<servlet-name> InfoServlet </servlet-name>
	<cache-helper-ref>myHelper</cache-helper-ref>
</cache-mapping>
</cache>

For more information about the sun-web.xml caching settings, see cache in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The CacheKeyGenerator Interface

The built-in default CacheHelper implementation allows web applications to customize the key generation. An application component (in a servlet or JSP) can set up a custom CacheKeyGenerator implementation as an attribute in the ServletContext.

The name of the context attribute is configurable as the value of the cacheKeyGeneratorAttrName property in the default-helper element of the sun-web.xml deployment descriptor. For more information, see default-helper in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

About the Servlet Engine

Servlets exist in and are managed by the servlet engine in the GlassFish Server. The servlet engine is an internal object that handles all servlet meta functions. These functions include instantiation, initialization, destruction, access from other components, and configuration management. This section covers the following topics:

Instantiating and Removing Servlets

After the servlet engine instantiates the servlet, the servlet engine calls the servlet’s init method to perform any necessary initialization. You can override this method to perform an initialization function for the servlet’s life, such as initializing a counter.

When a servlet is removed from service, the servlet engine calls the destroy method in the servlet so that the servlet can perform any final tasks and deallocate resources. You can override this method to write log messages or clean up any lingering connections that won’t be caught in garbage collection.

Request Handling

When a request is made, the GlassFish Server hands the incoming data to the servlet engine. The servlet engine processes the request’s input data, such as form data, cookies, session information, and URL name-value pairs, into an HttpServletRequest request object type.

The servlet engine also creates an HttpServletResponse response object type. The engine then passes both as parameters to the servlet’s service method.

In an HTTP servlet, the default service method routes requests to another method based on the HTTP transfer method: POST, GET, DELETE, HEAD, OPTIONS, PUT, or TRACE. For example, HTTP POST requests are sent to the doPost method, HTTP GET requests are sent to the doGet method, and so on. This enables the servlet to process request data differently, depending on which transfer method is used. Since the routing takes place in the service method, you generally do not override service in an HTTP servlet. Instead, override doGet, doPost, and so on, depending on the request type you expect.

To perform the tasks to answer a request, override the service method for generic servlets, and the doGet or doPost methods for HTTP servlets. Very often, this means accessing EJB components to perform business transactions, then collating the information in the request object or in a JDBC ResultSet object.

Using JavaServer Pages

The GlassFish Server supports the following JSP features:

For information about creating JSP files, see the JavaServer Pages web site at http://java.sun.com/products/jsp/index.jsp.

For information about Java Beans, see the JavaBeans web page at http://java.sun.com/javase/technologies/desktop/javabeans/index.jsp.

This section describes how to use JavaServer Pages (JSP files) as page templates in a GlassFish Server web application. This section contains the following topics:

JSP Tag Libraries and Standard Portable Tags

GlassFish Server supports tag libraries and standard portable tags. For more information, see the JavaServer Pages Standard Tag Library (JSTL) page at http://java.sun.com/products/jsp/jstl/index.jsp.

Web applications don’t need to bundle copies of the jsf-impl.jar or appserv-jstl.jar JSP tag libraries (in as-install/lib) to use JavaServerTM Faces technology or JSTL, respectively. These tag libraries are automatically available to all web applications.

However, the as-install/lib/appserv-tags.jar tag library for JSP caching is not automatically available to web applications. See JSP Caching, next.

JSP Caching

JSP caching lets you cache tag invocation results within the Java engine. Each can be cached using different cache criteria. For example, suppose you have invocations to view stock quotes, weather information, and so on. The stock quote result can be cached for 10 minutes, the weather report result for 30 minutes, and so on. JSP caching is described in the following topics:

For more information about response caching as it pertains to servlets, see Caching Servlet Results.

Enabling JSP Caching

To globally enable JSP caching, set the jspCachingEnabled property to true. The default is false. For example:


asadmin set server-config.web-container.property.jspCachingEnabled="true"

For more information about the asadmin set command, see the Oracle GlassFish Server 3.0.1 Reference Manual.

To enable JSP caching for a single web application, follow these steps:

  1. Extract the META-INF/appserv-tags.tld file from the as-install/glassfish/modules/web-glue.jar file.

  2. Create a new JAR file (for example, appserv-tags.jar) containing just the META-INF/appserv-tags.tld file previously extracted.

  3. Bundle this new JAR file in the WEB-INF/lib directory of your web application.

Note –

Web applications that use JSP caching without bundling the tag library are not portable.

Refer to GlassFish Server tags in JSP files as follows:

<%@ taglib prefix="prefix" uri="Sun ONE Application Server Tags" %>

Subsequently, the cache tags are available as <prefix:cache> and <prefix:flush>. For example, if your prefix is mypfx, the cache tags are available as <mypfx:cache> and <mypfx:flush>.

Caching Scope

JSP caching is available in three different scopes: request, session, and application. The default is application. To use a cache in request scope, a web application must specify the com.sun.appserv.web.taglibs.cache.CacheRequestListener in its web.xml deployment descriptor, as follows:

<listener>
   <listener-class>
      com.sun.appserv.web.taglibs.cache.CacheRequestListener
   </listener-class>
</listener>

Likewise, for a web application to utilize a cache in session scope, it must specify the com.sun.appserv.web.taglibs.cache.CacheSessionListener in its web.xml deployment descriptor, as follows:

<listener>
   <listener-class>
      com.sun.appserv.web.taglibs.cache.CacheSessionListener
   </listener-class>
</listener>

To utilize a cache in application scope, a web application need not specify any listener. The com.sun.appserv.web.taglibs.cache.CacheContextListener is already specified in the appserv-tags.tld file.

The cache Tag

The cache tag caches the body between the beginning and ending tags according to the attributes specified. The first time the tag is encountered, the body content is executed and cached. Each subsequent time it is run, the cached content is checked to see if it needs to be refreshed and if so, it is executed again, and the cached data is refreshed. Otherwise, the cached data is served.

Attributes of cache

The following table describes attributes for the cache tag.

Table 8–1 The cache Attributes

Attribute 

Default 

Description 

key

ServletPath_Suffix

(optional) The name used by the container to access the cached entry. The cache key is suffixed to the servlet path to generate a key to access the cached entry. If no key is specified, a number is generated according to the position of the tag in the page. 

timeout

60s

(optional) The time in seconds after which the body of the tag is executed and the cache is refreshed. By default, this value is interpreted in seconds. To specify a different unit of time, add a suffix to the timeout value as follows: s for seconds, m for minutes, h for hours, d for days. For example, 2h specifies two hours.

nocache

false

(optional) If set to true, the body content is executed and served as if there were no cache tag. This offers a way to programmatically decide whether the cached response is sent or whether the body has to be executed, though the response is not cached.

refresh

false

(optional) If set to true, the body content is executed and the response is cached again. This lets you programmatically refresh the cache immediately regardless of the timeout setting.

scope

application

(optional) The scope of the cache. Can be request, session, or application. See Caching Scope.

Example of cache

The following example represents a cached JSP file:

<%@ taglib prefix="mypfx" uri="Sun ONE Application Server Tags" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<mypfx:cache                 key="${sessionScope.loginId}"
			nocache="${param.nocache}"
			refresh="${param.refresh}"
			timeout="10m">
<c:choose>
	<c:when test="${param.page == 'frontPage'}">
		<%-- get headlines from database --%>
	</c:when>
	<c:otherwise>
		...
	</c:otherwise>
</c:choose>
</mypfx:cache>
<mypfx:cache timeout="1h">
<h2> Local News </h2>
	<%-- get the headline news and cache them --%>
</mypfx:cache>

The flush Tag

Forces the cache to be flushed. If a key is specified, only the entry with that key is flushed. If no key is specified, the entire cache is flushed.

Attributes of flush

The following table describes attributes for the flush tag.

Table 8–2 The flush Attributes

Attribute 

Default 

Description 

key

ServletPath_Suffix

(optional) The name used by the container to access the cached entry. The cache key is suffixed to the servlet path to generate a key to access the cached entry. If no key is specified, a number is generated according to the position of the tag in the page. 

scope

application

(optional) The scope of the cache. Can be request, session, or application. See Caching Scope.

Examples of flush

To flush the entry with key="foobar":

<mypfx:flush key="foobar"/>

To flush the entire cache:

<c:if test="${empty sessionScope.clearCache}">
   <mypfx:flush />
</c:if>

Options for Compiling JSP Files

GlassFish Server provides the following ways of compiling JSP source files into servlets:

Creating and Managing Sessions

This section describes how to create and manage HTTP sessions that allows users and transaction information to persist between interactions.

This section contains the following subsections:

Configuring Sessions

This section covers the following topics:

HTTP Sessions, Cookies, and URL Rewriting

To configure whether and how HTTP sessions use cookies and URL rewriting, edit the session-properties and cookie-properties elements in the sun-web.xml file for an individual web application. For more about the properties you can configure, see session-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide and cookie-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Coordinating Session Access

Make sure that multiple threads don’t simultaneously modify the same session object in conflicting ways.

This is especially likely to occur in web applications that use HTML frames where multiple servlets are executing simultaneously on behalf of the same client. A good solution is to ensure that one of the servlets modifies the session and the others have read-only access.

Saving Sessions During Redeployment

Whenever a redeployment is done, the sessions at that transit time become invalid unless you use the keepSessions=true property of the asadmin redeploy command. For example:


asadmin redeploy --properties keepSessions=true --name hello.war

For details, see the Oracle GlassFish Server 3.0.1 Reference Manual.

The new class loader of the redeployed application is used to deserialize any sessions previously saved. The usual restrictions about serialization and deserialization apply. For example, any application-specific class referenced by a session attribute may evolve only in a backward-compatible fashion. For more information about class loaders, see Chapter 2, Class Loaders.

Logging Session Attributes

You can write session attribute values to an access log. The access log format token %session.name% logs one of the following:

For more information about access logging and format tokens, see online help for the Access Log tab of the HTTP Service page in the Administration Console.

Session Managers

A session manager automatically creates new session objects whenever a new session starts. In some circumstances, clients do not join the session, for example, if the session manager uses cookies and the client does not accept cookies.

GlassFish Server offers these session management options, determined by the session-manager element’s persistence-type attribute in the sun-web.xml file:

Note –

If the session manager configuration contains an error, the error is written to the server log and the default (memory) configuration is used.

For more information, see session-manager in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The memory Persistence Type

This persistence type is not designed for a production environment that requires session persistence. It provides no session persistence. However, you can configure it so that the session state in memory is written to the file system prior to server shutdown.

To specify the memory persistence type for a specific web application, edit the sun-web.xml file as in the following example. The persistence-type attribute is optional, but must be set to memory if included. This overrides the web container availability settings for the web application.

<sun-web-app>
...
<session-config>
	<session-manager persistence-type="memory" />
		<manager-properties>
			<property name="sessionFilename" value="sessionstate" />
		</manager-properties>
	</session-manager>
	...
</session-config>
...
</sun-web-app>

The only manager property that the memory persistence type supports is sessionFilename, which is listed under manager-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide. The sessionFilename property specifies the name of the file where sessions are serialized and persisted if the web application or the server is stopped. To disable this behavior, specify an empty string as the value of sessionFilename.

For more information about the sun-web.xml file, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The file Persistence Type

This persistence type provides session persistence to the local file system, and allows a single server domain to recover the session state after a failure and restart. The session state is persisted in the background, and the rate at which this occurs is configurable. The store also provides passivation and activation of the session state to help control the amount of memory used. This option is not supported in a production environment. However, it is useful for a development system with a single server instance.

Note –

Make sure the delete option is set in the server.policy file, or expired file-based sessions might not be deleted properly. For more information about server.policy, see The server.policy File.

To specify the file persistence type for a specific web application, edit the sun-web.xml file as in the following example. Note that persistence-type must be set to file. This overrides the web container availability settings for the web application.

<sun-web-app>
...
<session-config>
	<session-manager persistence-type="file">
		<store-properties>
			<property name="directory" value="sessiondir" />
		</store-properties>
	</session-manager>
	...
</session-config>
...
</sun-web-app>

The file persistence type supports all the manager properties listed under manager-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide except sessionFilename, and supports the directory store property listed under store-properties in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

For more information about the sun-web.xml file, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Using Comet

This section explains the Comet programming technique and how to create and deploy a Comet-enabled application with the Oracle GlassFish Server.

The following topics are addressed here:

Introduction to Comet

Comet is a programming technique that allows a web server to send updates to clients without requiring the clients to explicitly request them.

This kind of programming technique is called server push, which means that the server pushes data to the client. The opposite style is client pull, which means that the client must pull the data from the server, usually through a user-initiated event, such as a button click.

Web applications that use the Comet technique can deliver updates to clients in a more timely manner than those that use the client-pull style while avoiding the latency that results from clients frequently polling the server.

One of the many use cases for Comet is a chat room application. When the server receives a message from one of the chat clients, it needs to send the message to the other clients without requiring them to ask for it. With Comet, the server can deliver messages to the clients as they are posted rather than expecting the clients to poll the server for new messages.

To accomplish this scenario, a Comet application establishes a long-lived HTTP connection. This connection is suspended on the server side, waiting for an event to happen before resuming. This kind of connection remains open, allowing an application that uses the Comet technique to send updates to clients when they are available rather than expecting clients to reopen the connection to poll the server for updates.

The Grizzly Implementation of Comet

A limitation of the Comet technique is that you must use it with a web server that supports non-blocking connections to avoid poor performance. Non-blocking connections are those that do not need to allocate one thread for each request. If the web server were to use blocking connections then it might end up holding many thousands of threads, thereby hindering its scalability.

The GlassFish server includes the Grizzly HTTP Engine, which enables asynchronous request processing (ARP) by avoiding blocking connections. Grizzly's ARP implementation accomplishes this by using the Java NIO API.

With Java NIO, Grizzly enables greater performance and scalability by avoiding the limitations experienced by traditional web servers that must run a thread for each request. Instead, Grizzly's ARP mechanism makes efficient use of a thread pool system and also keeps the state of requests so that it can keep requests alive without holding a single thread for each of them.

Grizzly supports two different implementations of Comet:

Client Technologies to Use With Comet

In addition to creating a web component that uses the Comet APIs, you need to enable your client to accept asynchronous updates from the web component. To accomplish this, you can use JavaScriptTM, IFrames, or a framework, such as Dojo.

An IFrame is an HTML element that allows you to include other content in an HTML page. As a result, the client can embed updated content in the IFrame without having to reload the page.

The example in this tutorial employs a combination of JavaScript and IFrames to allow the client to accept asynchronous updates. A servlet included in the example writes out JavaScript code to one of the IFrames. The JavaScript code contains the updated content and invokes a function in the page that updates the appropriate elements in the page with the new content.

The next section explains the two kinds of connections that you can make to the server. While you can use any of the client technologies listed in this section with either kind of connection, it is more difficult to use JavaScript with an HTTP-streaming connection.

Types of Comet Connections

When working with Comet, as implemented in Grizzly, you have two different ways to handle client connections to the server:

HTTP Streaming

The HTTP Streaming technique keeps a connection open indefinitely. It never closes, even after the server pushes data to the client.

In the case of HTTP streaming, the application sends a single request and receives responses as they come, reusing the same connection forever. This technique significantly reduces the network latency because the client and the server don't need to open and close the connection.

The basic life cycle of an application using HTTP-streaming is:

request --> suspend --> data available --> write response --> data available --> write response

The client makes an initial request and then suspends the request, meaning that it waits for a response. Whenever data is available, the server writes it to the response.

Long Polling

The long-polling technique is a combination of server-push and client-pull because the client needs to resume the connection after a certain amount of time or after the server pushes an update to the client.

The basic life cycle of an application using long-polling is:

request -> suspend --> data available --> write response --> resume

The client makes an initial request and then suspends the request. When an update is available, the server writes it to the response. The connection closes, and the client optionally resumes the connection.

How to Choose the Type of Connection

If you anticipate that your web application will need to send frequent updates to the client, you should use the HTTP-streaming connection so that the client does not have to frequently reestablish a connection. If you anticipate less frequent updates, you should use the long-polling connection so that the web server does not need to keep a connection open when no updates are occurring. One caveat to using the HTTP-streaming connection is that if you are streaming through a proxy, the proxy can buffer the response from the server. So, be sure to test your application if you plan to use HTTP-streaming behind a proxy.

Grizzly Comet

The following sections describe how to use Grizzly Comet.

The Grizzly Comet API

Grizzly's support for Comet includes a small set of APIs that make it easy to add Comet functionality to your web applications. The Grizzly Comet APIs that developers use most often are the following:

The way a developer would use this API in a web component is to perform the following tasks:

  1. Register the context path of the application with the CometContext object:

    CometEngine cometEngine = 
	CometEngine.getEngine();
CometContext cometContext = 
	cometEngine.register(contextPath)

  2. Register the CometHandler implementation with the CometContext object:

    cometContext.addCometHandler(handler)

  3. Notify one or more CometHandler implementations when an event happens:

    cometContext.notify((Object)(handler))

The Hidden Frame Example

This rest of this tutorial uses the Hidden Frame example to explain how to develop Comet-enabled web applications. You can download the example from grizzly.dev.java.net at Hidden example download. From there, you can download a prebuilt WAR file as well as a JAR file containing the servlet code.

The Hidden Frame example is so called because it uses hidden IFrames. The example allows multiple clients to increment a counter on the server. When a client increments the counter, the server broadcasts the new count to the clients using the Comet technique.

The Hidden Frame example uses the long-polling technique, but you can easily modify it to use HTTP-streaming by removing two lines. See To Notify the Comet Handler of an Event and To Create a HTML Page That Updates and Displays the Content for more information on converting the example to use the HTTP-streaming technique.

The client side of the example uses hidden IFrames with embedded JavaScript tags to connect to the server and to asynchronously post content to and accept updates from the server.

The server side of the example consists of a single servlet that listens for updates from clients, updates the counter, and writes JavaScript code to the client that allows it to update the counter on its page.

See Deploying and Running a Comet-Enabled Application for instructions on how to deploy and run the example.

When you run the example, the following happens:

  1. The index.html page opens.

  2. The browser loads three frames: The first one accesses the servlet using an HTTP GET; the second one loads the count.html page, which displays the current count; and the third one loads the button.html page, which is used to send the POST request.

  3. After clicking the button on the button.html page, the page submits a POST request to the servlet.

  4. The doPost method calls the onEvent method of the Comet handler and redirects the incremented count along with some JavaScript to the count.html page on the client.

  5. The updateCount() JavaScript function on the count.html page updates the counter on the page.

  6. Because this example uses long-polling, the JavaScript code on count.html calls doGet again to resume the connection after the servlet pushes the update.

Creating a Comet-Enabled Application

This section uses the Hidden Frame example application to demonstrate how to develop a Comet application. The main tasks for creating a simple Comet-enabled application are the following:

Developing the Web Component

This section shows you how to create a Comet-enabled web component by giving you instructions for creating the servlet in the Hidden Frame example.

Developing the web component involves performing the following steps:

  1. Create a web component to support Comet requests.

  2. Register the component with the Comet engine.

  3. Define a Comet handler that sends updates to the client.

  4. Add the Comet handler to the Comet context.

  5. Notify the Comet handler of an event using the Comet context.

ProcedureTo Create a Web Component to Support Comet

  1. Create an empty servlet class, like the following:

    import javax.servlet.*;

public class HiddenCometServlet extends HttpServlet {
	private static final long serialVersionUID = 1L;
private String contextPath = null;
	@Override
	public void init(ServletConfig config) throws ServletException {}

	@Override
	protected void doGet(HttpServletRequest req, 
	HttpServletResponse res) 
	throws ServletException, IOException {}

	@Override
	protected void doPost(HttpServletRequest req, 
	HttpServletResponse res)
	throws ServletException, IOException {);
}

  2. Import the following Comet packages into the servlet class:

    import com.sun.grizzly.comet.CometContext;
import com.sun.grizzly.comet.CometEngine;
import com.sun.grizzly.comet.CometEvent;
import com.sun.grizzly.comet.CometHandler;

  3. Import these additional classes that you need for incrementing a counter and writing output to the clients:

    import java.io.IOException;
import java.io.PrintWriter;
import java.util.concurrent.atomic.AtomicInteger;

  4. Add a private variable for the counter:

    private final AtomicInteger counter = new AtomicInteger();

ProcedureTo Register the Servlet With the Comet Engine

  1. In the servlet's init method, add the following code to get the component's context path:

    ServletContext context = config.getServletContext();
contextPath = context.getContextPath() + "/hidden_comet";

  2. Get an instance of the Comet engine by adding this line after the lines from Step 1:

     CometEngine engine = CometEngine.getEngine();

  3. Register the component with the Comet engine by adding the following lines after those from Step 2:

    CometContext cometContext = engine.register(contextPath);
cometContext.setExpirationDelay(30 * 1000);

ProcedureTo Define a Comet Handler to Send Updates to the Client

  1. Create a private class that implements CometHandler and add it to the servlet class:

    private class CounterHandler 
	implements CometHandler<HttpServletResponse> {
	private HttpServletResponse response;
}

  2. Add the following methods to the class:

    public void onInitialize(CometEvent event) 
	throws IOException {}

	public void onInterrupt(CometEvent event) 
		throws IOException {
		removeThisFromContext();
	}
	
	public void onTerminate(CometEvent event) 
		throws IOException {
		removeThisFromContext();
	}

	public void attach(HttpServletResponse attachment) {
            this.response = attachment;
	}

	private void removeThisFromContext() throws IOException {
		response.getWriter().close();
		CometContext context = 
			CometEngine.getEngine().getCometContext(contextPath);
		context.removeCometHandler(this);
	}

    You need to provide implementations of these methods when implementing CometHandler. The onInterrupt and onTerminate methods execute when certain changes occur in the status of the underlying TCP communication. The onInterrupt method executes when communication is resumed. The onTerminate method executes when communication is closed. Both methods call removeThisFromContext, which removes the CometHandler object from the CometContext object.

ProcedureTo Add the Comet Handler to the Comet Context

  1. Get an instance of the Comet handler and attach the response to it by adding the following lines to the doGet method:

    CounterHandler handler = new CounterHandler();
handler.attach(res);

  2. Get the Comet context by adding the following lines to doGet:

    CometEngine engine = CometEngine.getEngine();
CometContext context = engine.getCometContext(contextPath);

  3. Add the Comet handler to the Comet context by adding this line to doGet:

    context.addCometHandler(handler);

ProcedureTo Notify the Comet Handler of an Event

  1. Add an onEvent method to the CometHandler implementation class to define what happens when an event occurs:

    public void onEvent(CometEvent event) 
	throws IOException {
	if (CometEvent.NOTIFY == event.getType()) {
		int count = counter.get();
		PrintWriter writer = response.getWriter();
		writer.write("<script type='text/javascript'>" + 
			"parent.counter.updateCount('" + count + "')" +
			"</script>\n");
		writer.flush();
		event.getCometContext().resumeCometHandler(this);
	}
}

    This method first checks if the event type is NOTIFY, which means that the web component is notifying the CometHandler object that a client has incremented the count. If the event type is NOTIFY, the onEvent method gets the updated count, and writes out JavaScript to the client. The JavaScript includes a call to the updateCount() function, which will update the count on the clients' pages.

    The last line resumes the Comet request and removes it from the list of active CometHandler objects. By this line, you can tell that this application uses the long-polling technique. If you were to delete this line, the application would use the HTTP-Streaming technique.

    • For HTTP-Streaming:

      Add the same code as for long-polling, except do not include the following line:

      event.getCometContext().resumeCometHandler(this);

    You don't include this line because you do not want to resume the request. Instead, you want the connection to remain open.

  2. Increment the counter and forward the response by adding the following lines to the doPost method:

    counter.incrementAndGet();
CometEngine engine = CometEngine.getEngine();
CometContext<?> context = 
	engine.getCometContext(contextPath);
context.notify(null);
req.getRequestDispatcher("count.html").forward(req, res);

    When a user clicks the button, the doPost method is called. The doPost method increments the counter. It then obtains the current CometContext object and calls its notify method. By calling context.notify, the doPost method triggers the onEvent method you created in the previous step. After onEvent executes, doPost forwards the response to the clients.

Creating the Client Pages

Developing the HTML pages for the client involves performing these steps:

  1. Create a welcome HTML page, called index.html, that contains: one hidden frame for connecting to the servlet through an HTTP GET; one IFrame that embeds the count.html page, which contains the updated content; and one IFrame that embeds the button.html page, which is used for posting updates using HTTP POST.

  2. Create the count.html page that contains an HTML element that displays the current count and the JavaScript for updating the HTML element with the new count.

  3. Create the button.html page that contains a button for the users to submit updates.

ProcedureTo Create a HTML Welcome Page That Contains IFrames for Receiving and Sending Updates

  1. Create an HTML page called index.html.

  2. Add the following content to the page:

    <html>
	<head>
		<title>Comet Example: Counter with Hidden Frame</title>
	</head>
	<body>
  </body>
</html>

  3. Add IFrames for connecting to the server and receiving and sending updates to index.html in between the body tags:

    <frameset>
	<iframe name="hidden" src="hidden_comet" 
		frameborder="0" height="0" width="100%"></iframe>
	<iframe name="counter" src="count.html" 
		frameborder="0" height="100%" width="100%"></iframe>
<iframe name="button" src="button.html" frameborder="0" height="30%" widget="100%"></iframe>
</frameset>

    The first frame, which is hidden, points to the servlet by referencing its context path. The second frame displays the content from count.html, which displays the current count. The second frame displays the content from button.html, which contains the submit button for incrementing the counter.

ProcedureTo Create a HTML Page That Updates and Displays the Content

  1. Create an HTML page called count.html and add the following content to it:

    <html>
	<head>
	</head>
		<body>
			<center>
				<h3>Comet Example: Counter with Hidden Frame</h3>
				<p>
				<b id="count">&nbsp;</b>
				<p>
			</center>
		</body>
</html>

    This page displays the current count.

  2. Add JavaScript code that updates the count in the page. Add the following lines in between the head tags of count.html:

    <script type='text/javascript'>
	function updateCount(c) {
		document.getElementById('count').innerHTML = c;
		parent.hidden.location.href = "hidden_comet";
	};
</script>

    The JavaScript takes the updated count it receives from the servlet and updates the count element in the page. The last line in the updateCount() function invokes the servlet's doGet method again to reestablish the connection.

    • For HTTP-Streaming:

      Add the same code as for long-polling, except for the following line:

      parent.hidden.location.href = “hidden_comet”

      This line invokes the doGet method of CometServlet again, which would reestablish the connection. In the case of HTTP-Streaming, you want the connection to remain open. Therefore, you don't include this line of code.

ProcedureTo Create the HTML Page That Allows Submitting Updates

  1. Create an HTML page called button.html and add the following content to it:

    <html>
	<head>
	</head>
		<body>
			<center>
				<form method="post" action="hidden_comet">
					<input type="submit" value="Click">
				</form>
			</center>
		</body>
</html>

    This page displays a form with a button that allows a user to update the count on the server. The servlet will then broadcast the updated count to all clients.

Creating the Deployment Descriptor

This section describes how to create a deployment descriptor to specify how your Comet-enabled web application should be deployed.

ProcedureTo Create the Deployment Descriptor

  1. Create a file called web.xml and put the following contents in it:

    <?xml version="1.0" encoding="UTF-8"?>
	<web-app version="3.0"
		xmlns="http://java.sun.com/xml/ns/javaee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation=
			"http://java.sun.com/xml/ns/javaee 
			http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd ">
			
		<servlet>
			<servlet-name>HiddenCometServlet</servlet-name>
			<servlet-class>
				com.sun.grizzly.samples.comet.HiddenCometServlet
			</servlet-class>
			<load-on-startup>0</load-on-startup>
		</servlet>
		<servlet-mapping>
			<servlet-name>HiddenCometServlet</servlet-name>
			<url-pattern>/hidden_comet</url-pattern>
		</servlet-mapping>
	</web-app>

    This deployment descriptor contains a servlet declaration and mapping for HiddenCometServlet. The load-on-startup attribute must be set to 0 so that the Comet-enabled servlet will not load until the client makes a request to it.

Deploying and Running a Comet-Enabled Application

Before running a Comet-enabled application in the GlassFish Server, you need to enable Comet in the server. Then you can deploy the application just as you would any other web application.

When running the application, you need to connect to it from at least two different browsers to experience the effect of the servlet updating all clients in response to one client posting an update to the server.

Enabling Comet in the GlassFish Server

Before running a Comet-enabled application, you need to enable Comet in the HTTP listener for your application by setting a special attribute in the associated protocol configuration. The following example shows the asadmin set command that adds this attribute:

asadmin set server-config.network-config.protocols.protocol.http-1.http.comet-support-enabled="true"

Substitute the name of the protocol for http-1.

ProcedureTo Deploy the Example

These instructions tell you how to deploy the Hidden Frame example.

  1. Download grizzly-comet-hidden-1.7.3.1.war.

  2. Run the following command to deploy the example:

    as-install/bin/asadmin deploy grizzly-comet-hidden-1.7.3.1.war

ProcedureTo Run the Example

These instructions tell you how to run the Hidden Frame example.

  1. Open two web browsers, preferably two different brands of web browser.

  2. Enter the following URL in both browsers:


    http://localhost:8080/grizzly-comet-hidden/index.html

  3. When the first page loads in both browsers, click the button in one of the browsers and watch the count change in the other browser window.

Bayeux Protocol

The Bayeux protocol, often referred to as Cometd, greatly simplifies the use of Comet. No server-side coding is needed for servers such as GlassFish Server that support the Bayeux protocol. Just enable Comet and the Bayeux protocol, then write and deploy the client as described in the following tasks:

Enabling Comet

Before running a Comet-enabled application, you need to enable Comet in the HTTP listener for your application by setting a special attribute in the associated protocol configuration. The following example shows the asadmin set command that adds this attribute:

asadmin set server-config.network-config.protocols.protocol.http-1.http.comet-support-enabled="true"

Substitute the name of the protocol for http-1.

ProcedureTo Configure the web.xml File

To enable the Bayeux protocol on the GlassFish Server, you must reference the CometdServlet in your web application's web.xml file. In addition, if your web application includes a servlet, set the load-on-startup value for your servlet to 0 (zero) so that it will not load until the client makes a request to it.

  1. Open the web.xml file for your web application in a text editor.

  2. Add the following XML code to the web.xml file:

    <servlet>
   <servlet-name>Grizzly Cometd Servlet</servlet-name>
   <servlet-class>
      com.sun.grizzly.cometd.servlet.CometdServlet
   </servlet-class>
   <init-param>
      <description>
         expirationDelay is the long delay before a request is
         resumed. -1 means never.
      </description>
      <param-name>expirationDelay</param-name>
      <param-value>-1</param-value>
   </init-param>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>Grizzly Cometd Servlet</servlet-name>
   <url-pattern>/cometd/*</url-pattern>
</servlet-mapping>

    Note that the load-on-startup value for the CometdServlet is 1.

  3. If your web application includes a servlet, set the load-on-startup value to 0 for your servlet (not the CometdServlet) as follows:

    <servlet>
   ...
   <load-on-startup>0</load-on-startup>
</servlet>

  4. Save the web.xml file.

ProcedureTo Write, Deploy, and Run the Client

The examples in this task are taken from the example chat application that is posted and discussed at http://weblogs.java.net/blog/jfarcand/archive/2007/02/gcometd_introdu_1.html.

  1. Add script tags to the HTML page. For example:

    <script type="text/javascript" src="chat.js"></script>

  2. In the script, call the needed libraries. For example:

    dojo.require("dojo.io.cometd");

  3. In the script, use publish and subscribe methods to send and receive messages. For example:

    cometd.subscribe("/chat/demo", false, room, "_chat");
cometd.publish("/chat/demo", { user: room._username, chat: text});

  4. Deploy the web application as you would any other web application. For example:


    asadmin deploy cometd-example.war

  5. Run the application as you would any other web application.

    The context root for the example chat application is /cometd and the HTML page is index.html. So the URL might look like this:


    http://localhost:8080/cometd/index.html
See Also

For more information about deployment in the GlassFish Server, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.

For more information about the Bayeux protocol, see Bayeux Protocol.

For more information about the Dojo toolkit, see http://dojotoolkit.org/.

For information about pushing data from an external component such as an EJB module, see the example at http://blogs.sun.com/swchan/entry/java_api_for_cometd. Using this Grizzly Java API for Cometd makes your web application non-portable. Running your application on a server that doesn't support Grizzly Comet will not work.

For information about REpresentational State Transfer (RESTful) web services and Comet, see RESTful Web Services and Comet.

Advanced Web Application Features

This section includes summaries of the following topics:

Internationalization Issues

This section covers internationalization as it applies to the following:

The Server's Default Locale

To set the default locale of the entire GlassFish Server, which determines the locale of the Administration Console, the logs, and so on, use the Administration Console. Select the GlassFish Server component, the Advanced tab, and the Domain Attributes tab. Then type a value in the Locale field. For details, click the Help button in the Administration Console.

Servlet Character Encoding

This section explains how the GlassFish Server determines the character encoding for the servlet request and the servlet response. For encodings you can use, see http://java.sun.com/javase/6/docs/technotes/guides/intl/encoding.doc.html.

Servlet Request

When processing a servlet request, the server uses the following order of precedence, first to last, to determine the request character encoding:

For details about the parameter-encoding element, see parameter-encoding in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Servlet Response

When processing a servlet response, the server uses the following order of precedence, first to last, to determine the response character encoding:

Virtual Server Properties

You can set virtual server properties in the following ways:

Some virtual server properties can be set for a specific web application. For details, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide.

Class Loader Delegation

The Servlet specification recommends that a web application class loader look in the local class loader before delegating to its parent. To make the web application class loader follow the delegation model in the Servlet specification, set delegate="false" in the class-loader element of the sun-web.xml file. It’s safe to do this only for a web module that does not interact with any other modules.

The default value is delegate="true", which causes the web application class loader to delegate in the same manner as the other class loaders. Use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see Oracle GlassFish Server 3.0.1 Application Deployment Guide.

For a number of packages, including java.* and javax.*, symbol resolution is always delegated to the parent class loader regardless of the delegate setting. This prevents applications from overriding core Java runtime classes or changing the API versions of specifications that are part of the Java EE platform.

For general information about class loaders, see Chapter 2, Class Loaders.

Using the default-web.xml File

You can use the default-web.xml file to define features such as filters and security constraints that apply to all web applications.

For example, directory listings are disabled by default for added security. To enable directory listings, in your domain's default-web.xml file, search for the definition of the servlet whose servlet-name is equal to default, and set the value of the init-param named listings to true. Then redeploy your web application if it has already been deployed, or restart the server.

<init-param>
   <param-name>listings</param-name>
   <param-value>true</param-value>
</init-param>

If listings is set to true, you can also determine how directory listings are sorted. Set the value of the init-param named sortedBy to NAME, SIZE, or LAST_MODIFIED. Then redeploy your web application if it has already been deployed, or restart the server.

<init-param>
   <param-name>sortedBy</param-name>
   <param-value>LAST_MODIFIED</param-value>
</init-param>

The mime-mapping elements in default-web.xml are global and inherited by all web applications. You can override these mappings or define your own using mime-mapping elements in your web application's web.xml file. For more information about mime-mapping elements, see the Servlet specification.

You can use the Administration Console to edit the default-web.xml file. For details, click the Help button in the Administration Console. As an alternative, you can edit the file directly using the following steps.

ProcedureTo Use the default-web.xml File

  1. Place the JAR file for the filter, security constraint, or other feature in the domain-dir/lib directory.

  2. Edit the domain-dir/config/default-web.xml file to refer to the JAR file.

  3. Restart the server.

Configuring Logging and Monitoring in the Web Container

For information about configuring logging and monitoring in the web container using the Administration Console, click the Help button in the Administration Console. Logging and Monitor tabs are accessible from the Application Server page.

Header Management

In all Editions of the GlassFish Server, the Enumeration from request.getHeaders() contains multiple elements (one element per request header) instead of a single, aggregated value.

The header names used in HttpServletResponse.addXXXHeader() and HttpServletResponse.setXXXHeader() are returned as they were created.

Configuring Valves and Catalina Listeners

You can configure custom valves and Catalina listeners for web modules or virtual servers by defining properties. A valve class must implement the org.apache.catalina.Valve interface from Tomcat or previous GlassFish Server releases, or the org.glassfish.web.valve.GlassFishValve interface from the current GlassFish Server release. A listener class for a virtual server must implement the org.apache.catalina.ContainerListener or org.apache.catalina.LifecycleListener interface. A listener class for a web module must implement the org.apache.catalina.ContainerListener, org.apache.catalina.LifecycleListener, or org.apache.catalina.InstanceListener interface.

In the sun-web.xml file, valve and listener properties for a web module look like this:

<sun-web-app ...>
   ...
   <property name="valve_1" value="org.glassfish.extension.Valve"/>
   <property name="listener_1" value="org.glassfish.extension.MyLifecycleListener"/>
</sun-web-app>

You can define these same properties for a virtual server. For more information, see Virtual Server Properties.

Alternate Document Roots

An alternate document root (docroot) allows a web application to serve requests for certain resources from outside its own docroot, based on whether those requests match one (or more) of the URI patterns of the web application's alternate docroots.

To specify an alternate docroot for a web application or a virtual server, use the alternatedocroot_n property, where n is a positive integer that allows specification of more than one. This property can be a subelement of a sun-web-app element in the sun-web.xml file or a virtual server property. For more information about these elements, see sun-web-app in Oracle GlassFish Server 3.0.1 Application Deployment Guide or .

A virtual server's alternate docroots are considered only if a request does not map to any of the web modules deployed on that virtual server. A web module's alternate docroots are considered only once a request has been mapped to that web module.

If a request matches an alternate docroot's URI pattern, it is mapped to the alternate docroot by appending the request URI (minus the web application's context root) to the alternate docroot's physical location (directory). If a request matches multiple URI patterns, the alternate docroot is determined according to the following precedence order:

For example, the following properties specify three sun-web.xml docroots. The URI pattern of the first alternate docroot uses an exact match, whereas the URI patterns of the second and third alternate docroots use extension and longest path prefix matches, respectively.

<property name="alternatedocroot_1" value="from=/my.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_2" value="from=*.jpg dir=/srv/images/jpg"/>
<property name="alternatedocroot_3" value="from=/jpg/* dir=/src/images"/>

The value of each alternate docroot has two components: The first component, from, specifies the alternate docroot's URI pattern, and the second component, dir, specifies the alternate docroot's physical location (directory).

Suppose the above examples belong to a web application deployed at http://company22.com/myapp. The first alternate docroot maps any requests with this URL:


http://company22.com/myapp/my.jpg

To this resource:


/svr/images/jpg/my.jpg

The second alternate docroot maps any requests with a *.jpg suffix, such as:


http://company22.com/myapp/*.jpg

To this physical location:


/svr/images/jpg

The third alternate docroot maps any requests whose URI starts with /myapp/jpg/, such as:


http://company22.com/myapp/jpg/*

To the same directory as the second alternate docroot.

For example, the second alternate docroot maps this request:


http://company22.com/myapp/abc/def/my.jpg

To:


/srv/images/jpg/abc/def/my.jpg

The third alternate docroot maps:


http://company22.com/myapp/jpg/abc/resource

To:


/srv/images/jpg/abc/resource

If a request does not match any of the target web application's alternate docroots, or if the target web application does not specify any alternate docroots, the request is served from the web application's standard docroot, as usual.

Using a context.xml File

You can define a context.xml file for all web applications, for web applications assigned to a specific virtual server, or for a specific web application.

To define a global context.xml file, place the file in the domain-dir/config directory and name it context.xml.

Use the contextXmlDefault property to specify the name and the location, relative to domain-dir, of the context.xml file for a specific virtual server. Specify this property in one of the following ways:

To define a context.xml file for a specific web application, place the file in the META-INF directory and name it context.xml.

For more information about virtual server properties, see Virtual Server Properties. For more information about the context.xml file, see The Context Container. Context parameters, environment entries, and resource definitions in context.xml are supported in the GlassFish Server.

Enabling WebDav

To enable WebDav in the GlassFish Server, you edit the web.xml and sun-web.xml files as follows.

First, enable the WebDav servlet in your web.xml file:

<servlet>
   <servlet-name>webdav</servlet-name>
   <servlet-class>org.apache.catalina.servlets.WebdavServlet</servlet-class>
   <init-param>
      <param-name>debug</param-name>
      <param-value>0</param-value>
   </init-param>
   <init-param>
      <param-name>listings</param-name>
      <param-value>true</param-value>
   </init-param>
   <init-param>
      <param-name>readonly</param-name>
      <param-value>false</param-value>
   </init-param>
</servlet>

Then define the servlet mapping associated with your WebDav servlet in your web.xml file:

<servlet-mapping>
   <servlet-name>webdav</servlet-name>
   <url-pattern>/webdav/*</url-pattern>
</servlet-mapping>

To protect the WebDav servlet so other users can't modify it, add a security constraint in your web.xml file:

<security-constraint>
   <web-resource-collection>
      <web-resource-name>Login Resources</web-resource-name>
      <url-pattern>/webdav/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
      <role-name>Admin</role-name>
   </auth-constraint>
   <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
   </user-data-constraint>
   <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>default</realm-name>
   </login-config>
   <security-role>
      <role-name>Admin</role-name>
   </security-role>
</security-constraint>

Then define a security role mapping in your sun-web.xml file:

<security-role-mapping>
   <role-name>Admin</role-name>
   <group-name>Admin</group-name>
</security-role-mapping>

If you are using the file realm, create a user and password. For example:


asadmin create-file-user --groups Admin --authrealmname default admin

Enable the security manager as described in Enabling and Disabling the Security Manager.

You can now use any WebDav client by connecting to the WebDav servlet URL, which has this format:


http://host:port/context-root/webdav/file

For example:


http://localhost:80/glassfish-webdav/webdav/index.html

You can add the WebDav servlet to your default-web.xml file to enable it for all applications, but you can't set up a security role mapping to protect it.

Using SSI

To enable SSI (server-side includes) processing for a specific web module, add the SSIServlet to your web.xml file as follows:

<web-app>
   <servlet>
      <servlet-name>ssi</servlet-name>
      <servlet-class>org.apache.catalina.ssi.SSIServlet</servlet-class>
   </servlet>
   ...
   <servlet-mapping>
      <servlet-name>ssi</servlet-name>
      <url-pattern>*.shtml</url-pattern>
   </servlet-mapping>
   ...
   <mime-mapping>
      <extension>shtml</extension>
      <mime-type>text/html</mime-type>
   </mime-mapping>
</web-app>

To enable SSI processing for all web modules, un-comment the corresponding sections in the default-web.xml file.

If the mime-mapping is not specified in web.xml, GlassFish Server attempts to determine the MIME type from default-web.xml or the operating system default.

You can configure the following init-param values for the SSIServlet.

Table 8–3 SSIServlet init-param Values

init-param 

Type 

Default 

Description 

buffered

boolean

false

Specifies whether the output should be buffered. 

debug

int

0 (for no debugging)

Specifies the debugging level.  

expires

Long

Expires header in HTTP response not set

Specifies the expiration time in seconds. 

inputEncoding

String

operating system encoding 

Specifies encoding for the SSI input if there is no URL content encoding specified. 

isVirtualWebappRelative

boolean

false (relative to the given SSI file)

Specifies whether the virtual path of the #include directive is relative to the content-root.

outputEncoding

String

UTF-8 

Specifies encoding for the SSI output. 

For more information about SSI, see http://httpd.apache.org/docs/2.2/mod/mod_include.html.

Using CGI

To enable CGI (common gateway interface) processing for a specific web module, add the CGIServlet to your web.xml file as follows:

<web-app>
   <servlet>
      <servlet-name>cgi</servlet-name>
      <servlet-class>org.apache.catalina.servlets.CGIServlet</servlet-class>
   </servlet>
   ...
   <servlet-mapping>
      <servlet-name>cgi</servlet-name>
      <url-pattern>/cgi-bin/*</url-pattern>
   </servlet-mapping>
</web-app>

To enable CGI processing for all web modules, un-comment the corresponding sections in the default-web.xml file.

Package the CGI program under the cgiPathPrefix. The default cgiPathPrefix is WEB-INF/cgi. For security, it is highly recommended that the contents and binaries of CGI programs be prohibited from direct viewing or download. For information about hiding directory listings, see Using the default-web.xml File.

Invoke the CGI program using a URL of the following format:


http://host:8080/context-root/cgi-bin/cgi-name

For example:


http://localhost:8080/mycontext/cgi-bin/hello

You can configure the following init-param values for the CGIServlet.

Table 8–4 CGIServlet init-param Values

init-param 

Type 

Default 

Description 

cgiPathPrefix

String

WEB-INF/cgi

Specifies the subdirectory containing the CGI programs. 

debug

int

0 (for no debugging)

Specifies the debugging level.  

executable

String

perl

Specifies the executable for running the CGI script. 

parameterEncoding

String

System.getProperty("file.encoding", "UTF-8")

Specifies the parameter's encoding. 

passShellEnvironment

boolean

false

Specifies whether to pass shell environment properties to the CGI program. 

To work with a native executable, do the following:

  1. Set the value of the init-param named executable to an empty String in the web.xml file.

  2. Make sure the executable has its executable bits set correctly.

  3. Use directory deployment to deploy the web module. Do not deploy it as a WAR file, because the executable bit information is lost during the process of jar and unjar. For more information about directory deployment, see the Oracle GlassFish Server 3.0.1 Application Deployment Guide.