Appendix A Deployment Descriptor Files

This chapter includes the following sections:

• About Deployment Descriptor Files

• Migration Issues

• Java EE Standard Descriptors

• Sun Java System Web Server Descriptors

• The sun-web-app_2_5-0.dtd File

• Elements in the sun-web.xml File

• Sample Web Application XML Files

About Deployment Descriptor Files

The deployment descriptor conveys the elements and configuration information of a web application between application developers, application assemblers, and deployers. For Java Servlets v.2.5, the deployment descriptor is defined in terms of an XML schema document.

Migration Issues

Migration creates a detailed log in the user-specified log file. For every instance, a log is created in the following syntax: MIGRATION_<server instance name>_MMM_DD_YYYY_HH_MM_AM/PM.log.

If no log directory exists, the log file is stored at install_dir/admin-server/logs.

Java EE Standard Descriptors

This section describes the Java EE descriptors.

sun-web.xml

You define roles in the deployment descriptor file web.xml and the corresponding role mappings in the sun-web.xml deployment descriptor file for individually deployed web modules.

default-web.xml

default-web.xml is a global web deployment descriptor file that is shared by deployed web applications. It is used to configure the DefaultServlet and JspServlet servlets. In addition, it specifies: MIME mappings based on extensions Welcome files Global filters and security constraints Individual web applications inherit and might override the configuration settings inherited from default-web.xml with their own web.xml. The default-web.xml for each server instance is shared by all web applications deployed on the server instance. Depending on the configuration capabilities of the hosting application, a virtual server might replace the server-wide default-web.xml with its own. In that case, a virtual server's default-web.xml is shared by all web application deployed on the virtual server.

Sun Java System Web Server Descriptors

This section describes the Web Server descriptors.

The sun-web-app_2_5-0.dtd File

The sun-web-app_2_5-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_5-0.dtd file is located in the install_dir/lib/dtds directory.

---

Note –

Do not edit the sun-web-app_2_5-0.dtd file. Its contents change only with new versions of Web Server.

---

For general information about DTD files and XML, see the XML specification at http://www.w3.org/TR/2004/REC-xml-20040204.

Each element defined in a DTD file, which might be present in the corresponding XML file can contain subelements, and attributes described in the following sections.

• Subelements

• Data

• Attributes

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.

Table A–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, EMPTY or (#PCDATA) appears 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, no extra white space should appear 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     cachemax-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 Web 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

• Security Elements

• Session Elements

• Reference Elements

• Caching Elements

• Classloader Element

• JSP Element

• Internationalization Elements

This section also includes an alphabetical list of the elements for quick reference. See Alphabetical List of sun-web.xml Elements.

---

Note –

Subelements must be defined in the order in which they are listed in each section, unless otherwise noted.

---

Each sun-web.xml file must begin with the following DOCTYPE header:

<!DOCTYPE sun-web-app PUBLIC -//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.5//EN" http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">

For an alphabetical list of elements in sun-web.xml, see Alphabetical List of sun-web.xml Elements

General Elements

General elements are as follows:

• sun-web-app Element

• property Element

• description Element

sun-web-app Element

This element Web Server- specific configuration for a web application. This element is the root element. The sun-web.xml file contain only one sun-web-app.

Subelements

The following table describes subelements for the sun-web-app element.

Table A–2 sun-web-app Subelements

Element	Required	Description
context-root Element	zero or more	Contains the web context roots for the web application
servlet Element	zero or more	Specifies a principal name for a servlet, which is used for the run-as role defined in web.xml
session-config Element	zero or one	Specifies the session manager, session cookie, and other session-related information
resource-env-ref Element	zero or more	Maps the absolute JNDI name to the resource-env-ref in the corresponding Java EE XML file
resource-ref Element	zero or more	Maps the absolute JNDI name to the resource-ref in the corresponding Java EE XML file
service-ref Element	zero or more	Specifies runtime settings for a web service reference
cache Element	zero or one	Configures caching for web application components
class-loader Element	zero or one	Specifies classloader configuration information
jsp-config Element	zero or one	Specifies JSP configuration information
locale-charset-info Element	zero or one	Specifies internationalization settings
property Element	zero or more	Specifies a property, which has a name and a value
message-destination-name Element	zero or more	Specifies a logical message destination
webservice-description Element	zero or more	Specifies a web service description

Attributes

none

Properties

The following table describes the properties for the sun-web-app element.

Table A–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.
encodeCookies	true	If true, Web Server URL encodes cookies before sending them to the client. If you don’t want cookies to be encoded, add the following setting to sun-web.xmldirectly under the <sun-web-app> tag: <property name="encodeCookies" value="false"/> Do not embed this setting in any other tag.
tempdir	instance_dir/generated/	Specifies a temporary directory for use by this web application. 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.
reuseSessionID	false	If true, this property causes the web application to reuse the JSESSIONID value (if present) in the request header as the session ID when creating sessions. The default behavior of web applications is not to reuse session IDs. Instead, applications generate cryptographically random session IDs for new sessions.
relativeRedirectAllowed	false	If true, allows the web application to send a relative URL to the client using the HttpResponse.sendRedirect() API (that is, it suppresses the container from translating a relative URL to a fully qualified URL).

context-root Element

This element contains the web context root of the application or web applications. This overrides the corresponding element in the web.xml file.

Subelements

none

Attributes

none

property Element

Specifies a property that has a name and a value. A property adds configuration information to its parent element that is:

• optional with respect to Web Server but Needed by a system or object that Web Server doesn't have knowledge of, such as an LDAP server or a Java class

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

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

The properties that manager-properties element uses depends on the value of the parent session-manager element persistence-type attribute. For details, see the description of the session-manager element.

Subelement

The following table describes subelement for the property element.

Table A–4 property Subelement

Element	Required	Description
description Element	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the property element.

Table A–5 property Attributes

Attribute	Default	Description
name	none	Specifies the name of the property or variable
value	none	Specifies the value of the property or variable

description Element

This element contains a text description of the parent element.

Subelements

none

Attributes

none

Security Elements

The security elements are as follows:

• security-role-mapping Element

• servlet Element

• servlet-name Element

• role-name Element

• principal-name Element

• group-name Element

security-role-mapping Element

This element maps roles to users or groups in the currently active realm.

Subelements

The following table describes subelements for the security-role-mapping element.

Table A–6 security-role-mapping Subelements

Element	Required	Description
role-name Element	only one	Contains the role name
principal-name Element	requires at least one principal-name or group-name	Contains a principal (user) name in the current realm
group-name Element	requires at least one principal-name or group-name	Contains a group name in the current realm

Attributes

none

servlet Element

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

Table A–7 servlet Subelements

Element	Required	Description
servlet-name Element	only one	Contains the name of a servlet, which is matched to a servlet-name in web.xml.
principal-name Element	only one	Contains a principal (user) name in the current realm.

Attributes

none

servlet-name Element

This element 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 Element

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

Subelements

none

Attributes

none

principal-name Element

This element contains data that specifies a principal (user) name in the current realm.

Subelements

none

Attributes

none

group-name Element

This element contains data that specifies a group name in the current realm.

Subelements

none

Attributes

none

Session Elements

Session elements are as follows:

• session-config Element

• session-manager Element

• manager-properties Element

• store-properties Element

• session-properties Element

• cookie-properties Element

---

Note –

The session manager interface is unstable. An unstable interface might be experimental or transitional. This interface therefore change change incompatibly, be removed, or be replaced by a more stable interface in the next release.

---

session-config Element

This element specifies session configuration information.

Subelements

The following table describes subelements for the session-config element.

Table A–8 session-config Subelements

Element	Required	Description
session-manager Element	zero or one	Specifies session manager configuration information
session-properties Element	zero or one	Specifies session properties
cookie-properties Element	zero or one	Specifies session cookie properties

Attributes

none

session-manager Element

Specifies session manager information.

---

Note –

As of Web Server, you cannot define a session manager either for a single sign-on session or for a virtual server. You must define session managers at the level of web applications.

---

Subelements

The following table describes subelements for the session-manager element.

Table A–9 session-manager Subelements

Element	Required	Description
manager-properties Element	zero or one	Specifies session manager properties.
store-properties Element	zero or one	Specifies session persistence (storage) properties.

Attribute

The following table describes the persistence-type attribute 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 A–10 session-manager Attribute

Attribute	Default Value	Description
persistence-type	memory	(Optional) Specifies the session persistence mechanism. Allowed values are memory, file, s1ws60, and mmap. Setting the value of persistence type to memory is equivalent to using Web Server’s IWS60 without any store. Setting the value of persistence type to file is equivalent to using Web Server’s IWS60 with FileStore.

manager-properties Element

This element specifies session manager properties.

Subelement

The following table describes the property subelement for the manager-properties element.

Table A–11 manager-properties Subelements

Element	Required	Description
property Element	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.

Table A–12 manager-properties Properties

Property Name	Default Value	Description
reapIntervalSeconds	60	Specifies the number of seconds between checks for expired sessions.  Set this value lower than the frequency at which session data changes . For example, this value should be as low as possible 1 second for a hit counter servlet on a frequently accessed web site 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 path name of the file in which the session state is preserved between application restarts, if preserving the state is possible. A relative path name is relative to the temporary directory for this web application.  Applicable only if the persistence-type attribute of the session-manager Element element is memory.

store-properties Element

Specifies session persistence (storage) properties.

Subelement

The following table describes the property subelement for the store-properties element.

Table A–13 store-properties Subelement

Element	Required	Description
property Element	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.

Table A–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.  Set 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 web site 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 path name of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web application.

session-properties Element

This element specifies session properties.

Subelements

The following table describes the property subelement for the session-properties element.

Table A–15 session-properties Subelements

Element	Required	Description
property Element	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.

Table A–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 application. If set to 0 session expires immediately. 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.

cookie-properties Element

This element specifies session cookie properties.

Subelement

The following table describes the property subelement for the cookie-properties element.

Table A–17 cookie-properties Subelement

Element	Required	Description
property Element	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.

Table A–18 cookie-properties Properties

Property Name	Default Value	Description
cookiePath	Context path at which the web application is installed.	Specifies the path name that is set when the session tracking cookie is created. The browser sends the cookie if the path name for the request contains this path name. If set to / (root), the browser sends cookies to all URLs served by the Web 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. The default value of -1 indicates that the cookie never expires.
cookieDomain	unset	Specifies the domain for which the cookie is valid.
cookieComment	Sun Java System Web 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 Element

• resource-env-ref-name Element

• resource-ref Element

• service-ref Element

• res-ref-name Element

• default-resource-principal Element

• name Element

• password Element

• jndi-name Element

resource-env-ref Element

This element maps the res-ref-name Element in the corresponding Java EE 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.

Table A–19 resource-env-ref Subelements

Element	Required	Description
resource-env-ref-name Element	only one	Specifies the res-ref-name in the corresponding Java EE web.xml file resource-env-ref entry.
jndi-name Element	only one	Specifies the absolute jndi-name of a resource.

Attributes

none

resource-env-ref-name Element

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

Subelements

none

Attributes

none

service-ref Element

This element specifies the runtime settings for a web service reference. Runtime information is only needed in the following cases:

• To define the port used to resolve a container-managed port

• To define the default Stub/Call property settings for Stub objects

• To define the URL of a final WSDL document to be used instead of the one associated with service-ref in the standard Java EE deployment descriptor

Table A–20 service-ref Subelements

Element	Required	Description
service-ref-name Element	only one	Specifies the web service reference name relative to java:comp/env
port-info Element	zero or more	Specifies information for a port within a web service reference
call-property Element	zero or more	Specifies JAX-RPC property values that can be set on a javax.xml.rpc. Call object before it is returned to the web service client
service-impl-class Element	zero or more	Specifies the name of the generated service implementation class
service-qname Element	zero or one	Specifies the WSDL service element that is being referenced.

service-ref-name Element

This element specifies the web service reference name relative to java:comp/env.

Subelements

none

Attributes

none

port-info Element

Either a service-endpoint-interface or a wsdl-port or both ports must be specified. If both ports are specified, wsdl-port specifies the port that the container chooses for container-managed port selection. The same wsdl-port value must not appear in more than one port-info element within the same service-ref. If a service-endpoint-interface is using container-managed port selection, its value must not appear in more than one port-info element within the same service-ref.

Subelements

The following table describes subelements for the port-info element.

Table A–21 port-info Subelements

Element	Required	Description
service-endpoint-interface Element	zero or one	Specifies the web service reference name relative to java:comp/env.
wsdl-port Element	zero or one	Specifies the WSDL port.
stub-property Element	zero or one	Specifies JAX-RPC property values that are set on thejavax.xml.rpc.Stub object before it is returned to the web service client.
call-property Element	zero or one	Specifies JAX-RPC property values that are set on thejavax.xml.rpc.Stub object before it is returned to the web service client.
message-security-binding Element	zero or one	Specifies a custom authentication provider binding.

service-endpoint-interface Element

This element specifies the web service reference name relative to java:comp/env.

Subelements

none

Attributes

none

wsdl-port Element

Specifies the WSDL port.

Subelements

The following table describes subelements for the wsdl-port element

Table A–22 wsdl-port Subelements

Element	Required	Description
namespaceURI Element	only one	Specifies the namespace URI.
localpart Element	only one	Specifies the local part of a QNAME.

namespaceURI Element

This element specifies the namespace URI.

Subelements

none

Attributes

none

localpart Element

Specifies the local part of a QNAME.

Subelements

none

Attributes

none

stub-property Element

This element specifies JAX-RPC property values that are set on a javax.xml.rpc. Stub object before it is returned to the web service client. The property names can be any properties supported by the JAX-RPC Stub implementation.

Subelements

The following table describes subelements for the stub-property element.

Table A–23 stub-property subelements

Element	Required	Description
name Element	only one	Specifies the name of the entity.
value Element	only one	Specifies the value of the entity.

call-property Element

This element specifies JAX-RPC property values that can be set on a javax.xml.rpc call object before it is returned to the web service client. The property names can be any properties supported by the JAX-RPC Call implementation.

Table A–24 call-property Subelements

Element	Required	Description
name Element	only one	Specifies the name of the entity.
value Element	only one	Specifies the value of the entity.

wsdl-override Element

This element specifies a valid URL pointing to a final WSDL document. If not specified, the WSDL document associated with the service-ref in the standard J2EE deployment descriptor is used.

Subelements

none

Attributes

none

service-impl-class Element

Specifies the name of the generated service implementation class.

Subelements

none

Attributes

none

service-qname Element

This element specifies the WSDL service element that is being referred to

Subelements

The following table describes subelements for the service-qname element.

Table A–25 service-qname Subelements

Element	Required	Description
namespaceURI Element	only one	Specifies the namespace URI.
localpart Element	only one	Specifies the local part of a QNAME.

resource-ref Element

This element maps the res-ref-name Element in the corresponding Java EE web.xml file resource-ref entry to the absolute jndi-name Element 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 A–26 resource-ref Subelements

Element	Required	Description
res-ref-name Element	only one	Specifies the res-ref-name in the corresponding Java EE web.xml file resource-ref entry
jndi-name Element	only one	Specifies the absolute jndi-name of a resource
default-resource-principal Element	zero or one	Specifies the default principal (user) for the resource

Attributes

none

res-ref-name Element

This element contains data that specifies the res-ref-name in the corresponding Java EE web.xml file resource-ref entry.

Subelements

none

Attributes

none

default-resource-principal Element

This element 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 Message Queue's broker user repository.

Subelements

The following table describes subelements for the default-resource-principal element.

Table A–27 default-resource-principal Subelements

Element	Required	Description
name Element	only one	Contains the name of the principal
password Element	only one	Contains the password for the principal

Attributes

none

name Element

This element contains data that specifies the name of the principal.

Subelements

none

Attributes

none

password Element

This element contains data that specifies the password for the principal.

Subelements

none

Attributes

none

jndi-name Element

This element 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 Web 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 and JSP Cache Tags.

Caching elements are as follows:

• cache Element

• cache-helper Element

• default-helper

• cache-mapping Element

• url-pattern Element

• cache-helper-ref Element

• timeout Element

• refresh-field Element

• http-method Element

• key-field Element

• constraint-field Element

• value Element

cache Element

This element configures caching for web application components.

Subelements

The following table describes subelements for the cache element.

Table A–28 cache Subelements

Element	Required	Description
cache-helper Element	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 Element	zero or more	Specifies a cache property, which has a name and a value.
cache-mapping Element	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.

Table A–29 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.

Table A–30 cache Properties

Property Name	Default Value	Description
cacheClassName	com.sun.appserv.web .cache.LruCache	Specifies the fully qualified name of the class that implements the cache functionality. For a list of valid values, seeCache Class Names.
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.

Table A–31 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 Element

This element specifies a class that implements the CacheHelper interface. For details, see CacheHelper Interface.

Subelement

The following table describes the property subelements for the cache-helper element.

Table A–32 cache-helper Subelement

Element	Required	Description
property Element	zero or more	Specifies a property, which has a name and a value.

Attributes

The following table describes attributes for the cache-helper element.

Table A–33 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

This element allows you to change the properties of the built-in default cache-helper class.

Subelement

The following table describes the property subelements for the default-helper element.

Table A–34 default-helper Subelements

Element	Required	Description
property Element	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Property

The following table describes the cacheKeyGeneratorAttrName properties for the default-helper element.

Table A–35 default-helper Properties

Property Name	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 provide a customized key generator rather than using the default helper. See CacheKeyGenerator Interface .

cache-mapping Element

This element maps a URL pattern or a servlet name to its cacheability constraints.

Subelements

The following table describes subelements for the cache-mapping element.

Table A–36 cache-mapping Subelements

Element	Required	Description
servlet-name Element	requires one servlet-name or url-pattern	Contains the name of a servlet.
url-pattern Element	requires one servlet-name or url-pattern	Contains a servlet URL pattern for which caching is enabled.
cache-helper-ref Element	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.
cache-mapping Element	zero or more	Specifies the RequestDispatcher methods for which caching is to be enabled on the target resource. Valid values are REQUEST, FORWARD, INCLUDE, and ERROR (default: REQUEST).
timeout Element	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 Element	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 Element	zero or more if cache-helper-ref is not used	Contains an HTTP method that is eligible for caching.
key-field Element	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 Element	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 Element

This element contains data that specifies a servlet URL pattern for which caching is enabled. See the Java Servlet 2.5 specification.

Subelements

none

Attributes

none

cache-helper-ref Element

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

Subelements

none

Attributes

none

timeout Element

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.

Table A–37 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	context.attribute	(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.

refresh-field Element

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

Table A–38 refresh-field Attributes

Attribute	Default Value	Description
name	none	Specifies the input parameter name. If the parameter is present in the specified scope and its value is true, the cache will be refreshed.
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 Element

This element contains data that specifies an HTTP method that is eligible for caching. The default is GET.

Subelements

none

Attributes

none

key-field Element

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.5 specification, section SRV 4.4, for details on the Servlet Path.

Subelements

none

Attributes

The following table describes attributes for the key-field element.

Table A–39 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 Element

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

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

Subelement

The following table describes the value subelements for the constraint-field element.

Table A–40 constraint-field Subelements

Element	Required	Description
value Element	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.

Table A–41 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, session.id, 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 Element

This element specifies the value of the entity

Subelements

none

Attributes

none

Classloader Element

The Classloader element is named class-loader.

• class-loader Element

class-loader Element

This element configures the classloader for the web application.

Subelements

none

Attributes

The following table describes attributes for the class-loader element.

Table A–42 class-loader Attributes

Attribute	Default Value	Description
extra-class-path	null	(Optional) Specifies additional classpath settings for this web application. If this path is not an absolute path, it is treated as relative to <web-app> <path> value.
delegate	false	(Optional) If true, the web application follows the standard classloader delegation model and delegates to its parent classloader first before looking in the local classloader. If false, the web application 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.
dynamic-reload-interval	value of the dynamicreloadinterval attribute of the <jvm> element in server.xml	(Optional) Enables an application to override the dynamicreloadinterval setting in server.xml. Specifies the frequency (in seconds) at which a web application is checked for modifications, and then reloaded if modifications have been made. Setting this value to less than or equal to 0 disables dynamic reloading of the application. If not specified, the value from server.xml is used. For more information about server.xml, see Sun Java System Web Server 7.0 Update 1 Administrator’s Configuration File Reference.

JSP Element

The JSP elements is jsp-config.

• jsp-config Element

jsp-config Element

This element specifies JSP configuration information that enables web application to customize the compilation and execution of its JSP files.

Subelement

The following table describes the name subelement for the jsp-config element.

Table A–43 jsp-config Subelements

Element	Required	Description
name Element	zero or more	Specifies a property.

Attributes

none

Properties

The following table describes properties for the jsp-config element.

Table A–44 jsp-config Properties

Property Name	Default Value	Description
ieClassId	clsid:8AD9C840- 044E-11D1-B3E9- 00805F499D93	The Java Plug-in COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.
javaCompilerPlugin	internal JDK compiler (javac)	This property is deprecated in this release. By this, we mean this is supported in 7.0 but will NOT be supported in future release  If JSP Pages import classes from unnamed packages, the default-JDK compiler will throw a compile time error when JSP- generated servlets are compiled. To compile JSP- generated servlets, set the javaCompilerPlugin property to org.apache.jasper.compiler.SunJavaCompiler. Note: The jspc command-line compiler for JSPs no longer supports -javac option. Since this property is deprecated, you are strongly encouraged to modify JSPs so that the imported classes have a package name. See also the -deprecatedjavac switch of jspc, described in Compiling JSPs Using the Command-Line Compiler.
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.5.0/docs/guide/intl/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.
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	Default work directory for the web application	The working directory created for storing all of 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.
initial-capacity	32	Specifies the initial size of the hash table of compiled JSP classes (see the following example).

The following example illustrates the use of the initial-capacity property described in the table above. The example shows how you would configure a value of 1024:

<jsp-config> <property name=”initial-capacity” value=”1024” /></jsp-config>

Internationalization Elements

The internationalization elements are as follows:

• parameter-encoding Element

• locale-charset-info Element

• locale-charset-map Element

parameter-encoding Element

This element specifies a hidden field or default character set that determines the character encoding the web container uses to decode parameters for request.getParameter calls when the character set is not set in the request's Content-Type.

For encodings you can use, see

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

Attributes

The following table describes attributes for the parameter-encoding element.

Table A–45 parameter-encoding Attributes

Attribute	Default Value	Description
form-hint-field	none	The value of the hidden field in the form that specifies the parameter encoding.
default-charset	none	This value is used for parameter encoding if neither request.setCharacterEncoding() is called nor form-hint-field is found in the request.

Subelements

none

Attributes

none

locale-charset-info Element

Specifies the mapping between the locale and the character encoding that should be set in the Content-type header of the response if a servlet or JSP sets the response locale using the ServletResponse.setLocale method. This setting overrides the web container's default locale-to-charset mapping.

Subelements

The following table describes subelements for the locale-charset-info element.

Table A–46 locale-charset-info Subelements

Element	Required	Description
locale-charset-map Element	one or more	Maps a locale to a character set.
parameter-encoding Element	zero or one	Deprecated. Use the parameter-encoding element under sun-web-app instead. This setting is supported only for backward compatibility with applications developed under Web Server

Attributes

The following table describes the default-locale attributes for the locale-charset-info.

Table A–47 locale-charset-info Attributes

Attribute Value	Default Value
default-locale	none

locale-charset-map Element

This element maps a locale to a specific character encoding.

For encodings you can use, see:

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

Attributes

The following table describes attributes for the locale-charset-map element.

Table A–48 locale-charset-map Attributes

Attribute	Default Value	Description
locale	none	Specifies the locale name.
agent	none	Ignored in Web Server
charset	none	Specifies the character set for that locale.

The following table provides a locale-charset-map example, listing the locale and the corresponding charset:

Table A–49 locale-charset-map Example

Locale	Charset
ja	EUC-JP
zh	UTF-8

message-destination Element

This element specifies the name of a logical message-destination defined within an application. The message-destination-name matches the corresponding message-destination-name in the corresponding Java EE deployment descriptor file.

Subelements

The following table describes subelements for the message-destination element.

Table A–50 message-destination Subelements

Elements	Required	Description
message-destination-name Element	only one	Specifies the name of a logical message destination defined within the corresponding Java EE deployment descriptor file
jndi-name Element	only one	Specifies the jndi-name of the associated entity

message-destination-name Element

This element specifies the name of a logical message destination defined within the corresponding Java EE deployment descriptor file.

Subelements

none

webservice-description Element

This element specifies a name and optional publish location for a web service.

Subelements

The following table describes subelements for the webservice-description element

Table A–51 webservice-description Subelements

Element	Required	Description
webservice-description-name Element	only one	Specifies a unique name for the web service within a web
wsdl-publish-location Element	zero or one	Specifies the URL of a directory to which the web services WSDL is published during deployment

Attributes

none

webservice-description-name Element

This element specifies a unique name for the web service within a web.

Subelements

none

Attributes

none

wsdl-publish-location Element

This element specifies the URL of a directory to which a web service's WSDL is published during deployment. Any required files are published to this directory, preserving their location relative to the module-specific WSDL directory (META-INF/wsdl or WEB-INF/wsdl).

Subelements

none

Attributes

none

Alphabetical List of sun-web.xml Elements

This section provides an alphabetical list for the easy lookup of sun-web.xml elements.

cache Element

cache-helper Element

cache-helper-ref Element

cache-mapping Element

class-loader Element

constraint-field Element

context-root Element

cookie-properties Element

default-helper

default-resource-principal Element

description Element

group-name Element

http-method Element

jndi-name Element

jsp-config Element

key-field Element

locale-charset-info Element

locale-charset-map Element

manager-properties Element

message-destination Element

message-destination-name Element

message-security-binding Element

name Element

parameter-encoding Element

password Element

principal-name Element

property Element

refresh-field Element

res-ref-name Element

resource-env-ref Element

resource-env-ref-name Element

resource-ref Element

role-name Element

security-role-mapping Element

servlet Element

servlet-name Element

service-ref Element

session-config Element

session-manager Element

session-properties Element

store-properties Element

sun-web-app Element

timeout Element

url-pattern Element

value Element

webservice-description Element

webservice-description-name Element

webservice-endpoint Element

---

Note –

For a list of sun-web.xml elements by category, see Elements in the sun-web.xml File.

---

Sample Web Application XML Files

This section includes sample web.xml and sun-web.xml files

• Sample web.xml File

• Sample sun-web.xml File

Sample web.xml File

The following is the sample web.xml file.

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
   version="2.5">-
	<!--

   Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 
-->
-
	<web-app>
<display-name>webapps-caching</display-name>
-
	<servlet>
<servlet-name>ServCache</servlet-name>
<servlet-class>samples.webapps.caching.ServCache</servlet-class>
<load-on-startup>0</load-on-startup>
</servlet>
-
	<servlet-mapping>
<servlet-name>ServCache</servlet-name>
<url-pattern>/ServCache</url-pattern>
</servlet-mapping>
-
	<session-config>
<session-timeout>30</session-timeout>
</session-config>
-
	<taglib>
<taglib-uri>/com/sun/web/taglibs/cache</taglib-uri>
<taglib-location>/WEB-INF/sun-web-cache.tld</taglib-location>
</taglib>
</web-app>

Sample sun-web.xml File

The following example shows a sample sun-web.xml file.

<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1
Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">
 <!--

    Copyright 2006 Sun Microsystems, Inc. All rights reserved.
-->
-
	<sun-web-app>
-
	<session-config>
<session-manager/>
</session-config>
-
	<cache enabled="true" timeout-in-seconds="300">
-
	<cache-mapping>
<servlet-name>ServCache</servlet-name>
<key-field name="inputtext" scope="request.parameter"/>
-
	<constraint-field name="inputtext" scope="request.parameter">
<value>one</value>
<value>two</value>
</constraint-field>
</cache-mapping>
</cache>
</sun-web-app>