Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Application Server 7 Developer's Guide to Web Applications

Chapter 6
Assembling and Deploying Web Modules

This chapter describes how web modules are assembled and deployed in Sun ONE Application Server. For general assembly and deployment information, see the Sun ONE Application Server Developer’s Guide.

The following topics are presented in this chapter:


Web Application Structure

Web Applications have a directory structure, all accessible from a mapping to the application’s document root (for example, /hello). The document root contains JSP files, HTML files, and static files such as image files.

A WAR (web application archive) file contains a complete web application in compressed form.

A special directory under the document root, WEB-INF, contains everything related to the application that is not in the public document tree of the application. No file contained in WEB-INF can be served directly to the client. The contents of WEB-INF include:

The web application directory structure follows the structure outlined in the J2EE specification. Here is an example directory structure of a simple web application.

+ hello/

|--- index.jsp

|--+ META-INF/

|  |--- MANIFEST.MF

'--+ WEB-INF/

   |--- web.xml

   '--- sun-web.xml

Here is an example directory structure of a simple J2EE application containing a web module.

+ converter_1/

|--- converterClient.jar

|--+ META-INF/

|  |--- MANIFEST.MF

|  |--- application.xml

|  '--- sun-application.xml

|--+ war-ic_war/

|  |--- index.jsp

|  |--+ META-INF/

|  |  |--- MANIFEST.MF

|  '--+ WEB-INF/

|     |--- web.xml

|     '--- sun-web.xml

|--+ ejb-jar-ic_jar/

|  |--- Converter.class

|  |--- ConverterBean.class

|  |--- ConverterHome.class

|  '--+ META-INF/

|     |--- MANIFEST.MF

|     |--- ejb-jar.xml

|     '--- sun-ejb-jar.xml

'--+ app-client-ic_jar/

   |--- ConverterClient.class

   '--+ META-INF/

      |--- MANIFEST.MF

      |--- application-client.xml

      '--- sun-application-client.xml


Creating Web Deployment Descriptors

Sun ONE Application Server web modules include two deployment descriptor files:

The easiest way to create the web.xml and sun-web.xml files is to deploy a web module using the Administration interface or Sun ONE Studio 4. For more information, see the next section or the Sun ONE Application Server Developer’s Guide. For example web.xml and sun-web.xml files, see "Sample Web Module XML Files".

After you have created these files, you can edit them using the Administration interface or a combination of an editor and command line utilities such as Ant to reassemble and redeploy the updated deployment descriptor information. Apache Ant 1.4.1 is provided with Sun ONE Application Server. For more information, see the Sun ONE Application Server Developer’s Guide.


Deploying Web Applications

When you deploy, undeploy, or redeploy a web application, you do not need to restart the server. In other words, deployment is dynamic.

You can deploy a web application in these ways, which are described briefly:

For more detailed information about deployment, see the Sun ONE Application Server Developer’s Guide.

You can keep the generated source for JSPs by adding the -keepgenerated property to the jsp-config element in sun-web.xml. If you include this property when you deploy the web application, the generated source is kept in instance_dir/generated/jsp/j2ee-apps/app_name/module_name if it is in an application or instance_dir/generated/jsp/j2ee-modules/module_name if it is in an individually deployed web module.

Using the Command Line

To deploy a web application using the command line:

  1. Edit the deployment descriptor files (web.xml and sun-web.xml) by hand.
  2. Execute an Ant build command (such as build war) to reassemble the WAR module.
  3. Write the web application to a WAR file if desired. This is optional. For example:
  4. jar -cvf module_name.war *

  5. Use the asadmin deploy command to deploy the WAR module. The syntax is as follows:
  6. asadmin deploy --user admin_user [--password admin_password] [--passwordfile password_file] --host hostname --port adminport [--secure | -s] [--virtualservers virtual_servers] [--type application|ejb|web|connector] [--contextroot contextroot] [--force=true] [--precompilejsp=false] [--verify=false] [--name component_name] [--upload=true] [--retrieve local_dirpath] [--instance instance_name] filepath

    For example, the following command deploys a web application as an individual module:

    asadmin deploy --user jadams --password secret --host localhost --port 4848 --type web --instance server1 myWebApp.war

    If upload is set to false, the filepath must be an absolute path on the server machine.

Using the Administration Interface

To deploy a web application using the Administration interface:

  1. Open the Applications component under your server instance.
  2. Go to the Web Applications page.
  3. Click on the Deploy button.
  4. Enter the full path to the WAR module (or click on Browse to find it), then click on the OK button.
  5. Enter the web application name and the context root.
  6. You can also redeploy the web application if it already exists by checking the appropriate box. This is optional.

  7. Assign the web application to one or more virtual servers by checking the boxes next to the virtual server names.
  8. Click on the OK button.

Using Sun ONE Studio

You can use Sun ONE Studio 4, to assemble and deploy web applications. For more information about using Sun ONE Studio, see the Sun ONE Studio 4, Enterprise Edition Tutorial.


Note

In Sun ONE Studio, deploying web application is referred to as executing it.



Dynamic Reloading of Web Applications

If you make code changes to a web application and dynamic reloading is enabled, you do not need to redeploy the web application or restart the server. To enable dynamic reloading, you can do one of the following:

In addition, to load new servlet files, reload EJB related changes, or reload deployment descriptor changes, you must do the following:

  1. Create an empty file named .reload at the root of the deployed application:
  2. instance_dir/applications/j2ee-apps/app_name/.reload

    or individually deployed module:

    instance_dir/applications/j2ee-modules/module_name/.reload

  3. Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make the above changes.

For JSPs, changes are reloaded automatically at a frequency set in the reload-interval property of the jsp-config element in the sun-web.xml file. To disable dynamic reloading of JSPs, set the reload-interval property to -1.


The sun-web-app_2_3-0.dtd File

The sun-web-app_2_3-0.dtd file defines the structure of the sun-web.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sun-web-app_2_3-0.dtd file is located in the install_dir/lib/dtds directory.


Note

Do not edit the sun-web-app_2_3-0.dtd file; its contents change only with new versions of Sun ONE Application Server.


For general information about DTD files and XML, see the XML specification at:

http://www.w3.org/TR/REC-xml

Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:

Subelements

Elements can contain subelements. For example, the following file fragment defines the cache element.

<!ELEMENT cache (cache-helper*, default-helper?, property*, cache-mapping*)>

The ELEMENT tag specifies that a cache element can contain cache-helper, default-helper, property, and cache-mapping subelements.

The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.

Table 6-1  requirement rules and subelement suffixes

Subelement Suffix

Requirement Rule

element*

Can contain zero or more of this subelement.

element?

Can contain zero or one of this subelement.

element+

Must contain one or more of this subelement.

element (no suffix)

Must contain only one of this subelement.

If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.

Data

Some elements contain character data instead of subelements. These elements have definitions of the following format:

<!ELEMENT element-name (#PCDATA)>

For example:

<!ELEMENT description (#PCDATA)>

In the sun-web.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:

<description>class name of session manager</description>

Attributes

Elements that have ATTLIST tags contain attributes (name-value pairs). For example:

<!ATTLIST cache           max-capacity   CDATA     "4096"
                  timeout        CDATA     "30"
                  enabled        %boolean; "false">

A cache element can contain max-capacity, timeout, and enabled attributes.

The #REQUIRED label means that a value must be supplied. The #IMPLIED label means that the attribute is optional, and that Sun ONE Application Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.

Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.


Elements in the sun-web.xml File

This section describes the XML elements in the sun-web.xml file. Elements are grouped as follows:

General Elements

General elements are as follows:

sun-web-app

Defines Sun ONE Application Server specific configuration for a web module. This is the root element; there can only be one sun-web-app element in a sun-web.xml file.

Subelements

The following table describes subelements for the sun-web-app element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-2  sun-web-app subelements  

Element

Required

Description

security-role-mapping

zero or more

Maps roles to users or groups in the currently active realm.

servlet

zero or more

Specifies a principal name for a servlet, which is used for the run-as role defined in web.xml.

session-config

zero or one

Specifies session manager, session cookie, and other session-related information.

resource-env-ref

zero or more

Maps the absolute JNDI name to the resource-env-ref in the corresponding J2EE XML file.

resource-ref

zero or more

Maps the absolute JNDI name to the resource-ref in the corresponding J2EE XML file.

ejb-ref

zero or more

Maps the absolute JNDI name to the ejb-ref in the corresponding J2EE XML file.

cache

zero or one

Configures caching for web application components.

class-loader

zero or one

Specifies classloader configuration information.

jsp-config

zero or one

Specifies JSP configuration information.

locale-charset-info

zero or one

Specifies internationalization settings.

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the sun-web-app element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-3  sun-web-app properties

Property Name

Default Value

Description

crossContextAllowed

true

If true, allows this web application to access the contexts of other web applications using the ServletContext.getContext()method.

tempdir

instance_dir/generated/j2ee-apps/app_name

or

instance_dir/generated/j2ee-modules/module_name

Specifies a temporary directory for use by this web module. This value is used to construct the value of the javax.servlet.context.tempdir context attribute. Compiled JSPs are also placed in this directory.

singleThreadedServletPoolSize

5

Specifies the maximum number of servlet instances allocated for each SingleThreadModel servlet in the web application.

useResponseCTForHeaders

false

If true, header data is sent in the encoding specified in the method Response.setContentType(). Use this property to send non-ASCII characters in the headers.

property

Specifies a property, which has a name and a value. A property adds configuration information to its parent element that is one or both of the following:

For example, a manager-properties element can include property subelements:

<manager-properties>
  <property name="reapIntervalSeconds" value="20" />
</manager-properties>

Which properties a manager-properties element uses depends on the value of the parent session-manager element’s persistence-type attribute. For details, see the description of the session-manager element.

Subelements

The following table describes subelements for the property element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-4  property subelements  

Element

Required

Description

description

zero or one

Specifies an optional text description of a property.

Attributes

The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-5  property attributes

Attribute

Default

Description

name

none

Specifies the name of the property.

value

none

Specifies the value of the property.

description

Contains data that specifies a text description of the containing element.

Subelements

none

Attributes

none

Security Elements

Security elements are as follows:

security-role-mapping

Maps roles to users or groups in the currently active realm. See the Sun ONE Application Server Developer’s Guide for how to define the currently active realm.

Subelements

The following table describes subelements for the security-role-mapping element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-6  security-role-mapping subelements  

Element

Required

Description

role-name

only one

Contains the role name.

principal-name

requires at least one principal-name or group-name

Contains a principal (user) name in the current realm.

group-name

requires at least one principal-name or group-name

Contains a group name in the current realm.

Attributes

none

servlet

Specifies a principal name for a servlet, which is used for the run-as role defined in web-xml.

Subelements

The following table describes subelements for the servlet element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-7  servlet subelements  

Element

Required

Description

servlet-name

only one

Contains the name of a servlet, which is matched to a servlet-name in web.xml.

principal-name

only one

Contains a principal (user) name in the current realm.

Attributes

none

servlet-name

Contains data that specifies the name of a servlet, which is matched to a servlet-name in web.xml. This name must be present in web.xml.

Subelements

none

Attributes

none

role-name

Contains data that specifies the role-name in the security-role element of the web.xml file.

Subelements

none

Attributes

none

principal-name

Contains data that specifies a principal (user) name in the current realm.

Subelements

none

Attributes

none

group-name

Contains data that specifies a group name in the current realm.

Subelements

none

Attributes

none

Session Elements

Session elements are as follows:

session-config

Specifies session configuration information.

Subelements

The following table describes subelements for the session-config element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-8  session-config subelements  

Element

Required

Description

session-manager

zero or one

Specifies session manager configuration information.

session-properties

zero or one

Specifies session properties.

cookie-properties

zero or one

Specifies session cookie properties.

Attributes

none

session-manager

Specifies session manager information.

Subelements

The following table describes subelements for the session-manager element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-9  session-manager subelements  

Element

Required

Description

manager-properties

zero or one

Specifies session manager properties.

store-properties

zero or one

Specifies session persistence (storage) properties.

Attributes

The following table describes attributes for the session-manager element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-10  session-manager attributes  

Attribute

Default Value

Description

persistence-type

memory

(optional) Specifies the session persistence mechanism. Allowed values are memory and file.

The custom value is not implemented and should not be used.

manager-properties

Specifies session manager properties.

Subelements

The following table describes subelements for the manager-properties element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-11  manager-properties subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the manager-properties element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-12  manager-properties properties

Property Name

Default Value

Description

reapIntervalSeconds

60

Specifies the number of seconds between checks for expired sessions.

Setting this value lower than the frequency at which session data changes is recommended. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.

maxSessions

-1

Specifies the maximum number of active sessions, or -1 (the default) for no limit.

sessionFilename

none; state is not preserved across restarts

Specifies the absolute or relative pathname of the file in which the session state is preserved between application restarts, if preserving the state is possible. A relative pathname is relative to the temporary directory for this web module.

Applicable only if the persistence-type attribute of the session-manager element is memory.

store-properties

Specifies session persistence (storage) properties.

Subelements

The following table describes subelements for the store-properties element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-13  store-properties subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the store-properties element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-14  store-properties properties

Property Name

Default Value

Description

reapIntervalSeconds

60

Specifies the number of seconds between checks for expired sessions for those sessions that are currently swapped out.

Setting this value lower than the frequency at which session data changes is recommended. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.

directory

directory specified by javax.servlet.context.tempdir context attribute

Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web module.

session-properties

Specifies session properties.

Subelements

The following table describes subelements for the session-properties element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-15  session-properties subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the session-properties element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-16  session-properties properties

Property Name

Default Value

Description

timeoutSeconds

600

Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to 0 or less, sessions in this web module never expire.

If a session-timeout element is specified in the web.xml file, the session-timeout value overrides any timeoutSeconds value. If neither session-timeout nor timeoutSeconds is specified, the timeoutSeconds default is used.

Note that the session-timeout element in web.xml is specified in minutes, not seconds.

enableCookies

true

Uses cookies for session tracking if set to true.

enableURLRewriting

true

Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an encodeURL or encodeRedirectURL call in the servlet or JSP.

idLengthBytes

128

Specifies the number of bytes in this web module’s session ID.

cookie-properties

Specifies session cookie properties.

Subelements

The following table describes subelements for the cookie-properties element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-17  cookie-properties subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the cookie-properties element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-18  cookie-properties properties

Property Name

Default Value

Description

cookieName

JSESSIONID

Specifies the name of the cookie used for session tracking.

cookiePath

Context path at which the web module is installed.

Specifies the pathname that is set when the cookie is created. The browser sends the cookie if the pathname for the request contains this pathname. If set to / (slash), the browser sends cookies to all URLs served by the Sun ONE Application Server. You can set the path to a narrower mapping to limit the request URLs to which the browser sends cookies.

cookieMaxAgeSeconds

-1

Specifies the expiration time (in seconds) after which the browser expires the cookie.

cookieDomain

(unset)

Specifies the domain for which the cookie is valid.

cookieComment

Sun ONE Application Server Session Tracking Cookie

Specifies the comment that identifies the session tracking cookie in the cookie file. Applications can provide a more specific comment for the cookie.

Reference Elements

Reference elements are as follows:

resource-env-ref

Maps the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the resource-env-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-19   resource-env-ref subelements  

Element

Required

Description

resource-env-ref-name

only one

Specifies the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry.

jndi-name

only one

Specifies the absolute jndi-name of a resource.

Attributes

none

resource-env-ref-name

Contains data that specifies the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry.

Subelements

none

Attributes

none

resource-ref

Maps the res-ref-name in the corresponding J2EE web.xml file resource-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the resource-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-20  resource-ref subelements  

Element

Required

Description

res-ref-name

only one

Specifies the res-ref-name in the corresponding J2EE web.xml file resource-ref entry.

jndi-name

only one

Specifies the absolute jndi-name of a resource.

default-resource-principal

zero or one

Specifies the default principal (user) for the resource.

Attributes

none

res-ref-name

Contains data that specifies the res-ref-name in the corresponding J2EE web.xml file resource-ref entry.

Subelements

none

Attributes

none

default-resource-principal

Specifies the default principal (user) for the resource.

If this element is used in conjunction with a JMS Connection Factory resource, the name and password subelements must be valid entries in Sun ONE Message Queue’s broker user repository. See the “Security Management” chapter in the Sun ONE Message Queue Administrator’s Guide for details.

Subelements

The following table describes subelements for the default-resource-principal element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-21  default-resource-principal subelements  

Element

Required

Description

name

only one

Contains the name of the principal.

password

only one

Contains the password for the principal.

Attributes

none

name

Contains data that specifies the name of the principal.

Subelements

none

Attributes

none

password

Contains data that specifies the password for the principal.

Subelements

none

Attributes

none

ejb-ref

Maps the ejb-ref-name in the corresponding J2EE ejb-jar.xml file ejb-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the ejb-ref element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-22   ejb-ref subelements  

Element

Required

Description

ejb-ref-name

only one

Specifies the ejb-ref-name in the corresponding J2EE ejb-jar.xml file ejb-ref entry.

jndi-name

only one

Specifies the absolute jndi-name of a resource.

Attributes

none

ejb-ref-name

Contains data that specifies the ejb-ref-name in the corresponding J2EE ejb-jar.xml file ejb-ref entry.

Subelements

none

Attributes

none

jndi-name

Contains data that specifies the absolute jndi-name of a URL resource or a resource in the server.xml file.


Note

To avoid collisions with names of other enterprise resources in JNDI, and to avoid portability problems, all names in a Sun ONE Application Server application should begin with the string java:comp/env.


Subelements

none

Attributes

none

Caching Elements

For details about response caching as it pertains to servlets, see "Caching Servlet Results". For details about JSP caching, see "JSP Caching".

Caching elements are as follows:

cache

Configures caching for web application components.

Subelements

The following table describes subelements for the cache element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-23  cache subelements  

Element

Required

Description

cache-helper

zero or more

Specifies a custom class that implements the CacheHelper interface.

default-helper

zero or one

Allows you to change the properties of the default, built-in cache-helper class.

property

zero or more

Specifies a cache property, which has a name and a value.

cache-mapping

zero or more

Maps a URL pattern or a servlet name to its cacheability constraints.

Attributes

The following table describes attributes for the cache element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-24  cache attributes  

Attribute

Default Value

Description

max-entries

4096

(optional) Specifies the maximum number of entries the cache can contain. Must be a positive integer.

timeout-in-seconds

30

(optional) Specifies the maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed. Can be overridden by a timeout element.

enabled

false

(optional) Determines whether servlet and JSP caching is enabled. Legal values are on, off, yes, no, 1, 0, true, false.

Properties

The following table describes properties for the cache element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-25  cache properties  

Property

Default Value

Description

cacheClassName

com.sun.appserv.web.cache.LruCache

Specifies the fully qualified name of the class that implements the cache functionality. The "cacheClassName values" table below lists possible values.

MultiLRUSegmentSize

4096

Specifies the number of entries in a segment of the cache table that should have its own LRU (least recently used) list. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.MultiLruCache.

MaxSize

unlimited; Long.MAX_VALUE

Specifies an upper bound on the cache memory size in bytes (KB or MB units). Example values are 32 KB or 2 MB. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.BoundedMultiLruCache.

Cache Class Names

The following table lists possible values of the cacheClassName property. The left column lists the value, and the right column describes the kind of cache the value specifies.

Table 6-26  cacheClassName values  

Value

Description

com.sun.appserv.web.cache.LruCache

A bounded cache with an LRU (least recently used) cache replacement policy.

com.sun.appserv.web.cache.BaseCache

An unbounded cache suitable if the maximum number of entries is known.

com.sun.appserv.web.cache.MultiLruCache

A cache suitable for a large number of entries (>4096). Uses the MultiLRUSegmentSize property.

com.sun.appserv.web.cache.BoundedMultiLruCache

A cache suitable for limiting the cache size by memory rather than number of entries. Uses the MaxSize property.

cache-helper

Specifies a class that implements the CacheHelper interface. For details, see "CacheHelper Interface".

Subelements

The following table describes subelements for the cache-helper element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-27  cache-helper subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

The following table describes attributes for the cache-helper element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-28  cache-helper attributes  

Attribute

Default Value

Description

name

default

Specifies a unique name for the helper class, which is referenced in the cache-mapping element.

class-name

none

Specifies the fully qualified class name of the cache helper, which must implement the com.sun.appserv.web.CacheHelper interface.

default-helper

Allows you to change the properties of the built-in default cache-helper class.

Subelements

The following table describes subelements for the default-helper element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-29  default-helper subelements  

Element

Required

Description

property

zero or more

Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the default-helper element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-30  default-helper properties  

Property

Default Value

Description

cacheKeyGeneratorAttrName

Uses the built-in default cache-helper key generation, which concatenates the servlet path with key-field values, if any.

The caching engine looks in the ServletContext for an attribute with a name equal to the value specified for this property to determine whether a customized CacheKeyGenerator implementation is used. An application may provide a customized key generator rather than using the default helper.

See "CacheKeyGenerator Interface".

cache-mapping

Maps a URL pattern or a servlet name to its cacheability constraints.

Subelements

The following table describes subelements for the cache-mapping element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-31  cache-mapping subelements  

Element

Required

Description

servlet-name

requires one servlet-name or url-pattern

Contains the name of a servlet.

url-pattern

requires one servlet-name or url-pattern

Contains a servlet URL pattern for which caching is enabled.

cache-helper-ref

required if timeout, refresh-field, http-method, key-field, and constraint-field are not used

Contains the name of the cache-helper used by the parent cache-mapping element.

timeout

zero or one if cache-helper-ref is not used

Contains the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed.

refresh-field

zero or one if cache-helper-ref is not used

Specifies a field that gives the application component a programmatic way to refresh a cached entry.

http-method

zero or more if cache-helper-ref is not used

Contains an HTTP method that is eligible for caching.

key-field

zero or more if cache-helper-ref is not used

Specifies a component of the key used to look up and extract cache entries.

constraint-field

zero or more if cache-helper-ref is not used

Specifies a cacheability constraint for the given url-pattern or servlet-name.

Attributes

none

url-pattern

Contains data that specifies a servlet URL pattern for which caching is enabled. See the Servlet 2.3 specification section SRV. 11.2 for applicable patterns.

Subelements

none

Attributes

none

cache-helper-ref

Contains data that specifies the name of the cache-helper used by the parent cache-mapping element.

Subelements

none

Attributes

none

timeout

Contains data that specifies the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed. If not specified, the default is the value of the timeout attribute of the cache element.

Subelements

none

Attributes

The following table describes attributes for the timeout element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-32  timeout attributes  

Attribute

Default Value

Description

name

none

Specifies the timeout input parameter, whose value is interpreted in seconds. The field’s type must be java.lang.Long or java.lang.Integer.

scope

request.attribute

(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, request.attribute, and session.attribute.

refresh-field

Specifies a field that gives the application component a programmatic way to refresh a cached entry.

Subelements

none

Attributes

The following table describes attributes for the refresh-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-33  refresh-field attributes  

Attribute

Default Value

Description

name

none

Specifies the input parameter name.

scope

request.parameter

(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute.

http-method

Contains data that specifies an HTTP method that is eligible for caching. The default is GET.

Subelements

none

Attributes

none

key-field

Specifies a component of the key used to look up and extract cache entries. The web container looks for the named parameter, or field, in the specified scope.

If this element is not present, the web container uses the Servlet Path (the path section that corresponds to the servlet mapping that activated the current request). See the Servlet 2.3 specification, section SRV 4.4, for details on the Servlet Path.

Subelements

none

Attributes

The following table describes attributes for the key-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-34  key-field attributes  

Attribute

Default Value

Description

name

none

Specifies the input parameter name.

scope

request.parameter

(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute.

constraint-field

Specifies a cacheability constraint for the given url-pattern or servlet-name.

All constraint-field constraints must pass for a response to be cached. If there are value constraints, at least one of them must pass.

Subelements

The following table describes subelements for the constraint-field element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-35  constraint-field subelements  

Element

Required

Description

value

zero or more

Contains a value to be matched to the input parameter value.

Attributes

The following table describes attributes for the constraint-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-36  constraint-field attributes  

Attribute

Default Value

Description

name

none

Specifies the input parameter name.

scope

request.parameter

(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, request.attribute, and session.attribute.

cache-on-match

true

(optional) If true, caches the response if matching succeeds. Overrides the same attribute in a value subelement.

cache-on-match-failure

false

(optional) If true, caches the response if matching fails. Overrides the same attribute in a value subelement.

value

Contains data that specifies a value to be matched to the input parameter value. The matching is case sensitive. For example:

<value match-expr="in-range">1-60</value>

Subelements

none

Attributes

The following table describes attributes for the value element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-37  value attributes  

Attribute

Default Value

Description

match-expr

equals

(optional) Specifies the type of comparison performed with the value. Allowed values are equals, not-equals, greater, lesser, and in-range.

If match-expr is greater or lesser, the value must be a number. If match-expr is in-range, the value must be of the form n1-n2, where n1 and n2 are numbers.

cache-on-match

true

(optional) If true, caches the response if matching succeeds.

cache-on-match-failure

false

(optional) If true, caches the response if matching fails.

Classloader Elements

Classloader elements are as follows:

class-loader

Configures the classloader for the web module.

Subelements

none

Attributes

The following table describes attributes for the class-loader element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-38  class-loader attributes  

Attribute

Default Value

Description

extra-class-path

null

(optional) Specifies additional classpath settings for this web module.

delegate

false

(optional) If true, the web module follows the standard classloader delegation model and delegates to its parent classloader first before looking in the local classloader. If false, the web module follows the delegation model specified in the Servlet specification and looks in its classloader before looking in the parent classloader.

For a web component of a web service, you must set this value to true.

Legal values are on, off, yes, no, 1, 0, true, false.

JSP Elements

JSP elements are as follows:

jsp-config

Specifies JSP configuration information.

Subelements

The following table describes subelements for the jsp-config element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-39  jsp-config subelements  

Element

Required

Description

property

zero or more

Specifies a property.

Attributes

none

Properties

The following table describes properties for the jsp-config element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.

Table 6-40  jsp-config properties

Property Name

Default Value

Description

ieClassId

clsid:8AD9C840-044E-11D1-B3E9-00805F499D93

The Java plugin COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.

javaCompilerPlugin

The internal JDK compiler (javac)

The fully qualified class name of the Java compiler plug-in to be used. Not needed for the default compiler.

For example, to use the jikes compiler for JSP pages, set the javaCompilerPlugin property to org.apache.jasper.compiler.JikesJavaCompiler, then set the javaCompilerPath property to point to the jikes executable.

javaCompilerPath

none

Specifies the path to the executable of an out-of-process Java compiler such as jikes. Ignored for the default compiler. Needed only if the javaCompilerPlugin property is specified.

javaEncoding

UTF8

Specifies the encoding for the generated Java servlet. This encoding is passed to the Java compiler used to compile the servlet as well. By default, the web container tries to use UTF8. If that fails, it tries to use the javaEncoding value.

For encodings you can use, see:

http://java.sun.com/j2se/1.4/docs/guide/int l/encoding.doc.html

classdebuginfo

false

Specifies whether the generated Java servlets should be compiled with the debug option set (-g for javac).

keepgenerated

true

If set to true, keeps the generated Java files. If false, deletes the Java files.

largefile

false

If set to true, static HTML is stored is a separate data file when a JSP is compiled. This is useful when a JSP is very large, because it minimizes the size of the generated servlet.

mappedfile

false

If set to true, generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.

scratchdir

The default work directory for the web application

The working directory created for storing all the generated code.

reload-interval

0

Specifies the frequency (in seconds) at which JSP files are checked for modifications. Setting this value to 0 checks JSPs for modifications on every request. Setting this value to -1 disables checks for JSP modifications and JSP recompilation.

Internationalization Elements

Internationalization elements are as follows:

locale-charset-info

Specifies information about the application’s internationalization settings.

Subelements

The following table describes subelements for the locale-charset-info element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-41  locale-charset-info subelements  

Element

Required

Description

locale-charset-map

one or more

Maps a locale and an agent to a character set.

parameter-encoding

zero or one

Determines how the web container decodes parameters from forms for this web application according to a hidden field value.

Attributes

The following table describes attributes for the locale-charset-info element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-42  locale-charset-info attributes  

Attribute

Default Value

Description

default-locale

none

Specifies the default locale.

locale-charset-map

Maps locales and agents to character sets.

For encodings you can use, see:

http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html

Subelements

The following table describes subelements for the locale-charset-map element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table 6-43  locale-charset-map subelements  

Element

Required

Description

description

zero or one

Specifies an optional text description of a mapping.

Attributes

The following table describes attributes for the locale-charset-map element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-44  locale-charset-map attributes  

Attribute

Default Value

Description

locale

none

Specifies the locale name.

agent

none

(optional) Specifies the type of client that interacts with the application server. For a given locale, different agents may have different preferred character sets. The value of this attribute must exactly match the value of the user-agent HTTP request header sent by the client. See the "example agent attribute values" table for more information.

charset

none

Specifies the character set.

Example Agents

The following table specifies example agent attribute values. The left column lists the agent, and the right column lists the corresponding attribute value.

Table 6-45  example agent attribute values  

Agent

user-agent Header and agent Attribute Value

Internet Explorer 5.00 for Windows 2000

Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)

Netscape 4.7.7 for Windows 2000

Mozilla/4.77 [en] (Windows NT 5.0; U)

Netscape 4.7 for Solaris

Mozilla/4.7 [en] (X11; u; Sun OS 5.6 sun4u)

parameter-encoding

Specifies a hidden field that determines the character encoding the web container uses to decode parameters for request.getParameter calls when the charset is not set in the request’s content-type.

For encodings you can use, see:

http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html

Subelements

none

Attributes

The following table describes attributes for the parameter-encoding element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table 6-46  parameter-encoding attributes  

Attribute

Default Value

Description

form-hint-field

none

The name of the hidden field in the form that specifies the parameter encoding.


Sample Web Module XML Files

This section includes the following:

Sample web.xml File

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' 'http://java.sun.com/j2ee/dtds/web-app_2_2.dtd'>

<web-app>

  <display-name>webapps-simple</display-name>

  <description>

    The jakarta-tomcat-4.0.3 sample apps ports over to S1AS.

  </description>

  <distributable></distributable>

  <servlet>

    <servlet-name>HelloWorldExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.HelloWorldExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>RequestHeaderExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.RequestHeaderExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>SnoopServlet</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.SnoopServlet

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>servletToJsp</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.servletToJsp

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>RequestInfoExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.RequestInfoExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>SessionExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.SessionExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>CookieExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.CookieExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>RequestParamExample</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.RequestParamExample

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>SendMailServlet</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.SendMailServlet

    </servlet-class>

  </servlet>

  <servlet>

    <servlet-name>JndiServlet</servlet-name>

    <servlet-class>

      samples.webapps.simple.servlet.JndiServlet

    </servlet-class>

  </servlet>

  <servlet-mapping>

    <servlet-name>HelloWorldExample</servlet-name>

    <url-pattern>/helloworld</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>RequestHeaderExample</servlet-name>

    <url-pattern>/requestheader</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>SnoopServlet</servlet-name>

    <url-pattern>/snoop</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>servletToJsp</servlet-name>

    <url-pattern>/servletToJsp</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>RequestInfoExample</servlet-name>

    <url-pattern>/requestinfo</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>SessionExample</servlet-name>

    <url-pattern>/session</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>CookieExample</servlet-name>

    <url-pattern>/cookie</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>RequestParamExample</servlet-name>

    <url-pattern>/requestparam</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>SendMailServlet</servlet-name>

    <url-pattern>/SendMailServlet</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>JndiServlet</servlet-name>

    <url-pattern>/JndiServlet</url-pattern>

  </servlet-mapping>

  <welcome-file-list>

    <welcome-file>index.html</welcome-file>

  </welcome-file-list>

  <taglib>

    <taglib-uri>

      http://java.apache.org/tomcat/examples-taglib

    </taglib-uri>

    <taglib-location>

      /WEB-INF/tlds/example-taglib.tld

    </taglib-location>

  </taglib>

  <resource-ref>

    <res-ref-name>mail/Session</res-ref-name>

    <res-type>javax.mail.Session</res-type>

    <res-auth>Container</res-auth>

  </resource-ref>

  <security-constraint>

    <web-resource-collection>

      <web-resource-name>Protected Area</web-resource-name>

<!-- Define the context-relative URL(s) to be protected -->

      <url-pattern>/jsp/security/protected/*</url-pattern>

<!-- If you list http methods, only those methods are protected -->

      <http-method>DELETE</http-method>

      <http-method>GET</http-method>

      <http-method>POST</http-method>

      <http-method>PUT</http-method>

    </web-resource-collection>

    <auth-constraint>

  <!-- Anyone with one of the listed roles may access this area -->

      <role-name>tomcat</role-name>

      <role-name>role1</role-name>

    </auth-constraint>

  </security-constraint>

<!-- Environment entry examples -->

  <env-entry>

    <description>

      The maximum number of tax exemptions allowed to be set.

    </description>

    <env-entry-name>maxExemptions</env-entry-name>

    <env-entry-value>15</env-entry-value>

    <env-entry-type>java.lang.Integer</env-entry-type>

  </env-entry>

  <env-entry>

    <env-entry-name>minExemptions</env-entry-name>

    <env-entry-value>1</env-entry-value>

    <env-entry-type>java.lang.Integer</env-entry-type>

  </env-entry>

  <env-entry>

    <env-entry-name>foo/name1</env-entry-name>

    <env-entry-value>value1</env-entry-value>

    <env-entry-type>java.lang.String</env-entry-type>

  </env-entry>

  <env-entry>

    <env-entry-name>foo/bar/name2</env-entry-name>

    <env-entry-value>true</env-entry-value>

    <env-entry-type>java.lang.Boolean</env-entry-type>

  </env-entry>

  <env-entry>

    <env-entry-name>name3</env-entry-name>

    <env-entry-value>1</env-entry-value>

    <env-entry-type>java.lang.Integer</env-entry-type>

  </env-entry>

  <env-entry>

    <env-entry-name>foo/name4</env-entry-name>

    <env-entry-value>10</env-entry-value>

    <env-entry-type>java.lang.Integer</env-entry-type>

  </env-entry>

</web-app>

Sample sun-web.xml File

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 Servlet 2.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3- 0.dtd'>

<sun-web-app>

  <session-config>

    <session-manager/>

  </session-config>

  <resource-ref>

    <res-ref-name>mail/Session</res-ref-name>

    <jndi-name>mail/Session</jndi-name>

  </resource-ref>

  <jsp-config/>

</sun-web-app>



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.