Advanced Web Application Features

The following topics are addressed here:

• Internationalization Issues

• Virtual Server Properties

• Class Loader Delegation

• Using the default-web.xml File

• Configuring Logging and Monitoring in the Web Container

• Configuring Idempotent URL Requests

• Header Management

• Configuring Valves and Catalina Listeners

• Alternate Document Roots

• Using a context.xml File

• Enabling WebDav

• Using SSI

• Using CGI

Internationalization Issues

The following topics are addressed here:

• The Server's Default Locale

• Servlet Character Encoding

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.

Servlet Request

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

• The getCharacterEncoding method

• A hidden field in the form, specified by the form-hint-field attribute of the parameter-encoding element in the glassfish-web.xml file

• The default-charset attribute of the parameter-encoding element in the glassfish-web.xml file

• The default, which is ISO-8859-1

For details about the parameter-encoding element, see parameter-encoding in Oracle GlassFish Server 3.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:

• The setCharacterEncoding or setContentType method

• The setLocale method

• The default, which is ISO-8859-1

Virtual Server Properties

You can set virtual server properties in the following ways:

• You can define virtual server properties using the asadmin create-virtual-server command. For example:

  asadmin create-virtual-server --hosts localhost --property authRealm=ldap MyVS

  For details and a complete list of virtual server properties, see create-virtual-server(1).

• You can define virtual server properties using the asadmin set command. For example:

  asadmin set server-config.http-service.virtual-server.MyVS.property.authRealm="ldap"

  For details, see set(1).

• You can define virtual server properties using the Administration Console. Select the HTTP Service component under the relevant configuration, select Virtual Servers, and select the desired virtual server. Select Add Property, enter the property name and value, check the enable box, and select Save. For details and a complete list of virtual server properties, click the Help button in the Administration Console.

Some virtual server properties can be set for a specific web application. For details, see glassfish-web-app in Oracle GlassFish Server 3.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 glassfish-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 glassfish-web.xml, see Oracle GlassFish Server 3.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.

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.

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. Select Logger Settings under the relevant configuration, or select the Stand-Alone Instances component, select the instance from the table, and select the Monitor tab.

Configuring Idempotent URL Requests

An idempotent request is one that does not cause any change or inconsistency in an application when retried. To enhance the availability of your applications deployed on an GlassFish Server cluster, configure the load balancer to retry failed idempotent HTTP requests on all the GlassFish Server instances in a cluster. This option can be used for read-only requests, for example, to retry a search request.

The following topics are addressed here:

• Specifying an Idempotent URL

• Characteristics of an Idempotent URL

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

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 glassfish-web.xml file, valve and listener properties for a web module look like this:

<glassfish-web-app ...>
   ...
   <property name="valve_1" value="org.glassfish.extension.Valve"/>
   <property name="listener_1" value="org.glassfish.extension.MyLifecycleListener"/>
</glassfish-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 glassfish-web-app element in the glassfish-web.xml file or a virtual server property. For more information about these elements, see glassfish-web-app in Oracle GlassFish Server 3.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:

• Exact match

• Longest path match

• Extension match

For example, the following properties specify three glassfish-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:

• In the Administration Console, open the HTTP Service component under the relevant configuration. Open the Virtual Servers component and scroll down to the bottom of the page. Enter contextXmlDefault as the property name and the path and file name relative to domain-dir as the property value.

• Use the asadmin create-virtual-server command. For example:

  asadmin create-virtual-server --property contextXmlDefault=config/vs1ctx.xml vs1

• Use the asadmin set command for an existing virtual server. For example:

  asadmin set server-config.http-service.virtual-server.vs1.property.contextXmlDefault=config/myctx.xml

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 glassfish-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 glassfish-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 7-4 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 7-5 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.1 Application Deployment Guide.