7 Developing Web Applications

Caching Features

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

• Caching is configurable based on the servlet name or the URI.

• When caching is based on the URI, this includes user specified parameters in the query string. For example, a response from /garden/catalog?category=roses is different from a response from /garden/catalog?category=lilies. These responses are stored under different keys in the cache.

• Cache size, entry timeout, and other caching behaviors are configurable.

• Entry timeout is measured from the time an entry is created or refreshed. To override this timeout for an individual cache mapping, specify the cache-mapping subelement timeout.

• To determine caching criteria programmatically, write a class that implements the com.sun.appserv.web.cache.CacheHelper interface. For example, if only a servlet knows when a back end data source was last modified, you can write a helper class to retrieve the last modified timestamp from the data source and decide whether to cache the response based on that timestamp.

• To determine cache key generation programmatically, write a class that implements the com.sun.appserv.web.cache.CacheKeyGenerator interface. See The CacheKeyGenerator Interface.

• All non-ASCII request parameter values specified in cache key elements must be URL encoded. The caching subsystem attempts to match the raw parameter values in the request query string.

• Since newly updated classes impact what gets cached, the web container clears the cache during dynamic deployment or reloading of classes.

• The following HttpServletRequest request attributes are exposed.

  • com.sun.appserv.web.cachedServletName, the cached servlet target

  • com.sun.appserv.web.cachedURLPattern, the URL pattern being cached

• Results produced by resources that are the target of a RequestDispatcher.include() or RequestDispatcher.forward() call are cached if caching has been enabled for those resources. For details, see "cache-mapping" in Oracle GlassFish Server Application Deployment Guide and "dispatcher" in Oracle GlassFish Server Application Deployment Guide. These are elements in the glassfish-web.xml file.

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:

• The default cache timeout is 30 seconds.

• Only the HTTP GET method is eligible for caching.

• HTTP requests with cookies or sessions automatically disable caching.

• No special consideration is given to Pragma:, Cache-control:, or Vary: headers.

• The default key consists of the Servlet Path (minus pathInfo and the query string).

• A "least recently used" list is maintained to evict cache entries if the maximum cache size is exceeded.

• Key generation concatenates the servlet path with key field values, if any are specified.

• Results produced by resources that are the target of a RequestDispatcher.include() or RequestDispatcher.forward() call are never cached.

Caching Example

Here is an example cache element in the glassfish-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 glassfish-web.xml caching settings, see "cache" in Oracle GlassFish Server 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 glassfish-web.xml deployment descriptor. For more information, see "default-helper" in Oracle GlassFish Server Application Deployment Guide.

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.

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 Reference Manual.

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

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

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

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

Refer to GlassFish Server tags in JSP files as follows:

<%@ taglib prefix="prefix" uri="http://glassfish.org/taglibs/cache" %>

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 jspcachtags.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.

<%@ taglib prefix="mypfx" uri="http://glassfish.org/taglibs/cache" %>
<%@ 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.

<mypfx:flush key="foobar"/>

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

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 glassfish-web.xml file for an individual web application. For more about the properties you can configure, see "session-properties" in Oracle GlassFish Server Application Deployment Guide and "cookie-properties" in Oracle GlassFish Server Application Deployment Guide.

For information about configuring default session properties for the entire web container, see Using the default-web.xml File and the Oracle GlassFish Server High Availability Administration Guide.

Coordinating Session Access

Make sure that multiple threads don't simultaneously modify the same session object in conflicting ways. If the persistence type is replicated (see The replicated Persistence Type), the following message in the log file indicates that this might be happening:

Primary Key Constraint violation while saving session session_id

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 --keepstate=true option of the asadmin redeploy command. For example:

asadmin redeploy --keepstate=true --name hello.war

For details, see the Oracle GlassFish Server Reference Manual.

The default for --keepstate is false. This option is supported only on the default server instance, named server. It is not supported and ignored for any other target.

For web applications, this feature is applicable only if in the glassfish-web-app.xml file the persistence-type attribute of the session-manager element is file.

If any active web session fails to be preserved or restored, none of the sessions will be available when the redeployment is complete. However, the redeployment continues and a warning is logged.

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 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:

• The value of the session attribute with the name name

• NULL-SESSION-ATTRIBUTE-name if the named attribute does not exist in the session

• NULL-SESSION if no session exists

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.

Distributed Sessions and Persistence

A distributed HTTP session can run in multiple GlassFish Server instances, provided the following criteria are met:

• Each server instance has the same distributable web application deployed to it. The web-app element of the web.xml deployment descriptor file must have the distributable subelement specified.

• The web application uses high-availability session persistence. If a non-distributable web application is configured to use high-availability session persistence, a warning is written to the server log, and the session persistence type reverts to memory. See The replicated Persistence Type.

• All objects bound into a distributed session must be of the types listed in Table 7-3.

• The web application must be deployed using the deploy or deploydir command with the --availabilityenabled option set to true. See the Oracle GlassFish Server Reference Manual.

In the event of an instance or hardware failure, another server instance can take over a distributed session, with the following limitations:

• If a distributable web application references a Java EE component or resource, the reference might be lost. See Table 7-3 for a list of the types of references that HTTPSession failover supports.

• References to open files or network connections are lost.

For information about how to work around these limitations, see the Oracle GlassFish Server Deployment Planning Guide.

In the following table, No indicates that failover for the object type might not work in all cases and that no failover support is provided. However, failover might work in some cases for that object type. For example, failover might work because the class implementing that type is serializable.

For more information about the InitialContext, see Accessing the Naming Context. For more information about transaction recovery, see Using the Transaction Service. For more information about Administered Objects, see "Administering JMS Physical Destinations" in Oracle GlassFish Server Administration 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 glassfish-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.

<glassfish-web-app>
...

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

The only manager property that the memory persistence type supports is sessionFilename, which is listed under "manager-properties" in Oracle GlassFish Server 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. The default value is an empty string.

For more information about the glassfish-web.xml file, see the Oracle GlassFish Server 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.

To specify the file persistence type for a specific web application, edit the glassfish-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.

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

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

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

The replicated Persistence Type

The replicated persistence type uses other servers in the cluster for session persistence. Clustered server instances replicate session state. Each backup instance stores the replicated data in memory. This allows sessions to be distributed. For details, see Distributed Sessions and Persistence. In addition, you can configure the frequency and scope of session persistence. The other servers are also used as the passivation and activation store. Use this option in a production environment that requires session persistence.

To use the replicated persistence type, you must enable availability. Select the Availability Service component under the relevant configuration in the Administration Console. Check the Availability Service box. To enable availability for the web container, select the Web Container Availability tab, then check the Availability Service box. All instances in an GlassFish Server cluster should have the same availability settings to ensure consistent behavior. For details, see the Oracle GlassFish Server High Availability Administration Guide.

To change settings such as persistence frequency and persistence scope for the entire web container, use the Persistence Frequency and Persistence Scope drop-down lists on the Web Container Availability tab in the Administration Console, or use the asadmin set command. For example:

asadmin set 
server-config.availability-service.web-container-availability.persistence-frequency=time-based

For more information, see the description of the asadmin set command in the Oracle GlassFish Server Reference Manual.

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

<glassfish-web-app>
...
<session-config>
    <session-manager persistence-type="replicated">
        <manager-properties>
            <property name="persistenceFrequency" value="web-method" />
        </manager-properties>
        <store-properties>
            <property name="persistenceScope" value="session" />
        </store-properties>
    </session-manager>
    ...
</session-config>
...
</glassfish-web-app>

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

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

To specify that web sessions for which high availability is enabled are first buffered and then replicated using a separate asynchronous thread, use the --asyncreplication=true option of the asadmin deploy command. For example:

asadmin deploy --availabilityenabled=true --asyncreplication=true --name hello.war

If --asyncreplication is set to true (the default), performance is improved but availability is reduced. If the instance where states are buffered but not yet replicated fails, the states are lost. If set to false, performance is reduced but availability is guaranteed. States are not buffered but immediately transmitted to other instances in the cluster.

The coherence-web Persistence Type

Built on top of Oracle Coherence, Coherence*Web is an HTTP session management module dedicated to managing session state in clustered environments. Starting with Coherence 3.7 and GlassFish Server 3.1.2, there is a new feature of Coherence*Web called ActiveCache for GlassFish. ActiveCache for GlassFish provides Coherence*Web functionality in web applications deployed on GlassFish Servers. Within GlassFish Server, Coherence*Web functions as an additional web container persistence type, named coherence-web.

For information about how to configure and deploy Coherence*Web on GlassFish Server, see Using Coherence*Web with GlassFish Server.

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:

• Grizzly Comet — Based on ARP, this includes a set of APIs that you use from a web component to enable Comet functionality in your web application. Grizzly Comet is specific to the Oracle GlassFish Server.

• Bayeux Protocol — Often referred to as Cometd, it consists of the JSON-based Bayeux message protocol, a set of Dojo or Ajax libraries, and an event handler. The Bayeux protocol uses a publish/subscribe model for server/client communication. The Bayeux protocol is portable, but it is container dependent if you want to invoke it from an Enterprise Java Beans (EJB ) component. The Grizzly implementation of Cometd consists of a servlet that you reference from your web application.

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 JavaScript, 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

• Long Polling

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:

• CometContext: A Comet context, which is a shareable space to which applications subscribe to receive updates.

• CometEngine: The entry point to any component using Comet. Components can be servlets, JavaServer Pages ( JSP), JavaServer Faces components, or pure Java classes.

• CometEvent: Contains the state of the CometContext object

• CometHandler: The interface an application implements to be part of one or more Comet contexts.

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.

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.

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

Creating the Deployment Descriptor

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

<?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>

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.

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

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.

To 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.

To Write, Deploy, and Run the Client

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 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 REpresentational State Transfer (RESTful) web services and Comet, see RESTful Web Services and Comet.

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 domain component. 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://download.oracle.com/javase/6/docs/technotes/guides/intl/encoding.doc.html.

To 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.

Specifying an Idempotent URL

To configure idempotent URL response, specify the URLs that can be safely retried in idempotent-url-pattern elements in the glassfish-web.xml file. For example:

<idempotent-url-pattern url-pattern="sun_java/*" no-of-retries="10"/>

For details, see "idempotent-url-pattern" in Oracle GlassFish Server Application Deployment Guide.

If none of the server instances can successfully serve the request, an error page is returned.

Characteristics of an Idempotent URL

Since all requests for a given session are sent to the same application server instance, and if that GlassFish Server instance is unreachable, the load balancer returns an error message. Normally, the request is not retried on another GlassFish Server instance. However, if the URL pattern matches that specified in the glassfish-web.xml file, the request is implicitly retried on another GlassFish Server instance in the cluster.

In HTTP, some methods (such as GET) are idempotent, while other methods (such as POST) are not. In effect, retrying an idempotent URL should not cause values to change on the server or in the database. The only difference should be a change in the response received by the user.

Examples of idempotent requests include search engine queries and database queries. The underlying principle is that the retry does not cause an update or modification of data.

A search engine, for example, sends HTTP requests with the same URL pattern to the load balancer. Specifying the URL pattern of the search request to the load balancer ensures that HTTP requests with the specified URL pattern are implicitly retried on another GlassFish Server instance.

For example, if the request URL sent to the GlassFish Server is of the type /search/something.html, then the URL pattern can be specified as /search/*.

Examples of non-idempotent requests include banking transactions and online shopping. If you retry such requests, money might be transferred twice from your account.