Advanced Web Application Features

This section includes summaries of the following topics:

• Internationalization Issues

• Virtual Servers

• Default Web Modules

• Class Loader Delegation

• Using the default-web.xml File

• Configuring Logging and Monitoring in the Web Container

• Header Management

• Configuring Valves and Catalina Listeners

• Alternate Document Roots

• Redirecting URLs

• Using a context.xml File

• Enabling WebDav

• Using mod_jk

• Using SSI

• Using CGI

• Using PHP

• Using Scala and Lift

Internationalization Issues

This section covers internationalization as it applies to the following:

• The Server's Default Locale

• Servlet Character Encoding

The Server's Default Locale

To set the default locale of the entire Enterprise Server, which determines the locale of the Administration Console, the logs, and so on, use the Administration Console. Select the Enterprise 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 Enterprise 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:

• The getCharacterEncoding() method

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

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

• The default, which is ISO-8859-1

For details about the parameter-encoding element, see parameter-encoding in Sun GlassFish Enterprise Server v3 Prelude 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 Servers

A virtual server, also called a virtual host, is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers can serve content using the same or different host names, port numbers, or IP addresses. The HTTP service directs incoming web requests to different virtual servers based on the URL.

When you first install the Enterprise Server, a default virtual server is created. You can also assign a default virtual server to each new HTTP listener you create.

Web applications can be assigned to virtual servers during deployment. A web module can be assigned to more than one virtual server, and a virtual server can have more than one web module assigned to it.

If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about deployment, see the Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

For more information about virtual servers, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.

To Assign a Default Virtual Server

1. In the Administration Console, open the HTTP Service component under the relevant configuration.

2. Open the HTTP Listeners component under the HTTP Service component.

3. Select or create a new HTTP listener.

4. Select from the Default Virtual Server drop-down list.

   For more information, see Default Web Modules.

See Also

For details, click the Help button in the Administration Console from the HTTP Listeners page.

To Assign Virtual Servers

1. Deploy the application or web module and assign the desired virtual servers to it.

   For more information, see Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

2. In the Administration Console, open the HTTP Service component under the relevant configuration.

3. Open the Virtual Servers component under the HTTP Service component.

4. Select the virtual server to which you want to assign a default web module.

5. Select the application or web module from the Default Web Module drop-down list.

   For more information, see Default Web Modules.

See Also

For details, click the Help button in the Administration Console from the Virtual Servers page.

Default Web Modules

A default web module can be assigned to the default virtual server and to each new virtual server. For details, see Virtual Servers. To access the default web module for a virtual server, point the browser to the URL for the virtual server, but do not supply a context root. For example:

http://myvserver:3184/

A virtual server with no default web module assigned serves HTML or JavaServer Pages (JSP) content from its document root, which is usually domain-dir/docroot. To access this HTML or JSP content, point your browser to the URL for the virtual server, do not supply a context root, but specify the target file.

For example:

http://myvserver:3184/hellothere.jsp

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 Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

For Prelude, the delegate value is ignored and assumed to be set to true.

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, you can disable directory listings for added security. 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 false. Then redeploy your web application if it has already been deployed.

<init-param>
   <param-name>listings</param-name>
   <param-value>false</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. Logging and Monitor tabs are accessible from the Application Server page.

Header Management

In all Editions of the Enterprise 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 Enterprise Server releases, or the org.glassfish.web.valve.GlassFishValve interface from the current Enterprise 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>

In the domain.xml file, valve and listener properties for a virtual server look like this:

<virtual-server ...>
   ...
   <property name="valve_1" value="org.glassfish.extension.Valve"/>
   <property name="listener_1" value="org.glassfish.extension.MyLifecycleListener"/>
</virtual-server>

You can define these properties for a virtual server in one of the following ways, then restart the server:

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

  asadmin set server-config.http-service.virtual-server.MyVS.property.valve_1="org.glassfish.extension.Valve"

• 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, click the Help button in the Administration Console.

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 element in the domain.xml file. For more information about these elements, see sun-web-app in Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide and virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.

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

Redirecting URLs

You can specify that a request for an old URL is treated as a request for a new URL. This is called redirecting a URL.

To specify a redirected URL for a virtual server, use the redirect_n property, where n is a positive integer that allows specification of more than one. This property is a subelement of a virtual-server element in the domain.xml file. For more information about this element, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference. Each of these redirect_n properties is inherited by all web applications deployed on the virtual server.

The value of each redirect_n property has two components, which may be specified in any order:

The first component, from, specifies the prefix of the requested URI to match.

The second component, url-prefix, specifies the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix.

For example:

<property name="redirect_1" value="from=/dummy url-prefix=http://etude"/>

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 --hosts localhost --property contextXmlDefault=config/vs1context.xml vs1

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

  asadmin set server-config.http-service.virtual-server.server.property.contextXmlDefault=config/mycontext.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 servers, see Virtual Servers. 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 Enterprise Server.

Enabling WebDav

To enable WebDav in the Enterprise 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 --user admin --host localhost --port 4848 --terse=true 
--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 mod_jk

To set up mod_jk, follow these steps:

1. Obtain and install Apache 2.0.x or 2.2.x HTTP Server (http://httpd.apache.org/).

2. Configure the following files:

   • /etc/httpd/conf/httpd.conf

   • /etc/httpd/conf/worker.properties or domain-dir/config/glassfish-jk.properties (to use non-default values of attributes described at http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html)

   Examples of these files are shown after these steps. If you use both worker.properties and glassfish-jk.properties files, the file referenced by httpd.conf, or referenced by httpd.conf first, takes precedence.

3. Start httpd.

4. Enable mod_jk using the following command:

   asadmin set server-config.http-service.http-listener.listener.property.jkEnabled=true

   For example:

   asadmin set server-config.http-service.http-listener.http-listener1.property.jkEnabled=true

   Or you can use the following deprecated command, provided for backward compatibility:

   asadmin create-jvm-options -Dcom.sun.enterprise.web.connector.enableJK=8009

5. If you are using the glassfish-jk.properties file and not referencing it in httpd.conf, point to it using the following command:

   asadmin create-jvm-options -Dcom.sun.enterprise.web.connector.enableJK.propertyFile=domain-dir/config/glassfish-jk.properties

6. Restart the Enterprise Server.

Here is an example httpd.conf file:

LoadModule jk_module /usr/lib/httpd/modules/mod_jk.so
JkWorkersFile /etc/httpd/conf/worker.properties
# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel debug
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send all jsp requests to GlassFish
JkMount /*.jsp worker1
# Send all glassfish-test requests to GlassFish
JkMount /glassfish-test/* worker1

Here is an example worker.properties or glassfish-jk.properties file:

# Define 1 real worker using ajp13
worker.list=worker1
# Set properties for worker1 (ajp13)
worker.worker1.type=ajp13
worker.worker1.host=localhost.localdomain
worker.worker1.port=8009
worker.worker1.lbfactor=50
worker.worker1.cachesize=10
worker.worker1.cache_timeout=600
worker.worker1.socket_keepalive=1
worker.worker1.socket_timeout=300

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, Enterprise 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.

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.

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 Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

Using PHP

To enable PHP, deploy the Quercus PHP interpreter to the Enterprise Server as a web module as follows:

1. Download the Quercus interpreter from http://quercus.caucho.com/.

2. Deploy the WAR file you downloaded to the Enterprise Server.

3. To verify that your PHP engine is working, point your browser to the default PHP script that comes with the Quercus interpreter, which is http://localhost:8080/quercus-3.1.6/.

4. The Quercus application directory is located at domain-dir/applications/quercus-3.1.6/. Place your PHP application in a subdirectory of the Quercus directory, for example domain-dir/applications/quercus-3.1.6/myapp/. To point your browser to the PHP application, enter http://localhost:8080/quercus-3.1.6/myapp/.

For more information about using the Quercus PHP interpreter, see the documentation at http://quercus.caucho.com/quercus-3.1/doc/quercus.xtp.

Using Scala and Lift

Scala is a general purpose programming language designed to express common programming patterns in a concise, elegant, and type-safe way. It smoothly integrates features of object-oriented and functional languages. It is also fully interoperable with Java. For details, see http://www.scala-lang.org/.

Lift is an expressive and elegant framework for writing web applications using Scala. Lift stresses the importance of security, maintainability, scalability and performance, while allowing for high levels of developer productivity. For details, see http://liftweb.net/.

It is common practice to start a Lift web application using Maven. Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. For details, see http://maven.apache.org/.

To create a new Lift project, use Maven interactively in one of these ways:

mvn archetype:generate -DarchetypeCatalog=http://scala-tools.org/

Or:

mvn org.apache.maven.plugins:maven-archetype-plugin:1.0-alpha-7:create \ 
 -DarchetypeGroupId=net.liftweb                             \
 -DarchetypeArtifactId=lift-archetype-blank                 \
 -DarchetypeVersion=0.7.1                                   \
 -DremoteRepositories=http://scala-tools.org/repo-releases  \
 -DgroupId=__my.liftapp__ -DartifactId=__liftapp__

Or:

mvn org.apache.maven.plugins:maven-archetype-plugin:1.0-alpha-7:create \ 
 -DarchetypeGroupId=net.liftweb                             \
 -DarchetypeArtifactId=lift-archetype-basic                 \
 -DarchetypeVersion=0.7.1                                   \
 -DremoteRepositories=http://scala-tools.org/repo-releases  \
 -DgroupId=__my.liftapp__ -DartifactId=__liftapp__

After coding your application, build the WAR file using the mvn package command. Then deploy the WAR file to the Enterprise Server as you would any other web application.