Sun ONE Web Server 6.1 Programmer's Guide to Web Applications |
Chapter 6
Deploying Web ApplicationsThis chapter describes how web applications are assembled and deployed in Sun ONE Web Server, and has the following sections:
Web Application StructureWeb applications have a directory structure, which is fully 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 file (Web 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. The following is an example directory structure of a simple web application:
+ hello/
|--- index.jsp
|--+ META-INF/
| |--- MANIFEST.MF
'--+ WEB-INF/
|--- web.xml
'--- sun-web.xml
Creating Web Deployment DescriptorsSun ONE Web Server web applications include two deployment descriptor files:
- A J2EE standard file (web.xml), described in the Java Servlet 2.3 specification (chapter SRV .13, “Deployment Descriptor”). You can find the specification here:
http://java.sun.com/products/servlet/download.html
- An optional Sun ONE Web Server-specific file (sun-web.xml), described later in this chapter.
The easiest way to create the web.xml and sun-web.xml files is to deploy a web application using Sun ONE Studio. For example web.xml and sun-web.xml files, see "Sample Web Application XML Files."
Deploying Web ApplicationsWhen you deploy, undeploy, or redeploy a web application, you do not need to restart the server. Deployment is dynamic.
You can deploy a web application in the following ways, which are described briefly in this section:
Using the Administration Interface
- In the Server Manager interface, click the Virtual Server Class tab.
The Manage a Class of Virtual Servers page displays.
- Select a class of virtual servers, and then click Manage.
The Class Manager interface displays.
- Select a virtual server, and then click Manage.
The Virtual Server Manager interface displays.
- Click the Web Applications tab, and then click the Deploy Web Application link.
The Deploy Web Application page displays.
- Enter the following information:
- WAR File On. Select Local Machine when uploading a WAR file to your server, or Server Machine when the WAR file already resides there.
- WAR File Path. Enter the path on the local or server machine to the WAR file containing the web application. On server machines, enter the absolute path to the WAR file. On local machines, you can browse the available paths.
- Application URI. Enter the URI on the virtual server for the web application.
- Installation Directory. Enter the absolute path to the directory on the server machine from which the contents of the WAR file will be extracted. If the directory does not exist, a directory will be created.
- Click OK.
For more information about using the Administration interface to manage Sun ONE Web Server, see the Sun ONE Web Server 6.1 Administrator’s Guide.
Deploying a Web Application using wdeploy
Before you can deploy a web application manually, you must make sure that the server_root/bin/https/bin directory is in your path.
You can use the wdeploy utility at the command line to deploy a WAR file into a virtual server web application environment as follows:
wdeploy deploy -u uri_path -i instance -v vs_id [-d directory] war_file
You can also delete a virtual server web application:
wdeploy delete -u uri_path -i instance -v vs_id hard|soft
You can also list the web application URIs and directories for a virtual server:
wdeploy list -i instance -v vs_id
The following table describes the command parameters. The left column lists the parameter, and the right column describes the parameter.
When you execute the wdeploy deploy command, two things happen:
Example usage of the command is as follows:
wdeploy deploy -u /hello -i server.sun.com -v acme.com
<server_root>/plugins/java/sample/webapps/simple/webapps-simple.warAfter you have deployed an application, you can access it from a browser as follows:
http://vs_urlhost[:vs_port]/uri_path/[index_page]
The following table describes the parts of the URL. The left column lists the part, and the right column describes what the part means.
For example:
http://acme.com:80/hello/index.jsp
- or -
http://acme.com/hello/
Using Sun ONE Studio
Sun ONE Web Server 6.1 supports Sun ONE Studio 5, Standard Edition. You can use Sun ONE Studio to assemble and deploy web applications.
Sun ONE Studio technology is Sun's powerful, extensible, integrated development environment (IDE) for Java technology developers. Sun ONE Studio 5 is based on NetBeans software, and integrated with the Sun ONE platform. (Sun ONE Web Server 6.1 also supports NetBeans 3.5 and 3.5.1.)
Sun ONE Studio support is available on all platforms supported by Sun ONE Web Server 6.1. The plugin for the Web Server can be obtained in the following ways:
- From the Companion CD in the Sun ONE Web Server 6.1 Media Kit
- By using the AutoUpdate feature of Sun ONE Studio
- From the download center for Sun ONE Web Server 6.1 at
http://www.sun.com/software/download/inter_ecom.html
For information about using the web application features in Sun ONE Studio 5, explore the resources at
http://developers.sun.com/prodtech/javatools/jsstandard/reference/docs/index.htmlThe behavior of the Sun ONE Studio 5 plugin for Sun ONE Web Server 6.1 is the same as that for Sun ONE Application Server 7. If you’re using the "Web Application Tutorial" at the site listed above, for instance, you would set the Sun ONE Web Server 6.1 instance as the default, and then take the same actions described in the tutorial.
Also see the following NetBeans tutorial
http://usersguide.netbeans.org/tutorials/webapps/index.htmlFor more information about Sun ONE Studio 5, visit
http://www.sun.com/software/sundev/jde/
Note
For basic information about using Sun ONE Studio to debug web applications, also see "Using Sun ONE Studio for Debugging" in this guide.
Enabling and Disabling Web ApplicationsSun ONE Web Server 6.1 allows you to enable or disable a web application. You can do so in either of the following ways, as discussed in this section:
Using the Administration Interface
To enable or disable a deployed web application using the Administrator interface, perform the following steps:
- Access the Administration Server, select the server instance, and click Manage.
- Click the Virtual Server Class tab.
- Select the virtual server class that contains the virtual server instance in which the web application is deployed, and click Manage.
- Select the virtual server in which the web application is deployed, and click Manage.
- Click the Web Applications tab, and then click the Edit Web Applications link.
- From the Action drop-down list, select Enable or Disable to enable or disable a specific web application.
- Click OK.
Editing the server.xml File
By default, an application is automatically enabled with the value set to true in the server-id/config/server.xml file. You can disable the application by setting the value to false.
Example:
<WEBAPP uri="/catalog" path="/export/apps/catalog" enabled="false"/>
For more information, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Dynamic Reloading of Web ApplicationsIf 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 must edit the following attribute of the server.xml file's JAVA element, then restart the server:
dynamicreloadinterval=integer
where integer specifies the interval (in seconds) after which a deployed application will be checked for modifications and reloaded if necessary. To enable dynamic reloading, you must specify a value greater than 0.
The server.xml setting is the default value for all applications. An individual application can override the value for dynamicreloadinterval by specifying a value to the class-loader element in the sun-web.xml file.
For information about sun-web.xml, see the following section, "The sun-web-app_2_3-1.dtd File." For details about server.xml, see the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
In addition, to load new servlet files or reload deployment descriptor changes, you must do the following:
- Create an empty file named .reload at the root of the deployed module. For example:
instance_dir/webapps/vs_id/uri/.reload
where vs_id is the virtual server ID in which the web application is deployed, and uri is the value of the uri attribute of the <WEBAPP> element.
- 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.
ClassloadersIn a Java Virtual Machine (JVM), the classloaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the classloaders loads the relevant class into the environment.
Classloaders in the Sun ONE Web Server 6.1 runtime follow the hierarchy shown in the following figure.
Figure 6-1 Classloader Runtime Hierarchy
Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a classloader delegates classloading to its parent before attempting to load a class itself. If the parent classloader can't load a class, the findClass()method is called on the classloader subclass. In effect, a classloader is responsible for loading only the classes not available to the parent.
The exception is the Web Application Classloader, which follows the delegation model in the Servlet specification. The Web Application Classloader looks in the local classloader before delegating to its parent. You can make the Web Application Classloader delegate to its parent first by setting delegate="true" in the class-loader element of the sun-web.xml file. For more information, see "Classloader Elements."
The following table describes Sun ONE Web Server 6.1 classloaders. The left column lists the classloaders, and the right column lists descriptions of those classloaders and the files they examine.
Table 6-3 Sun ONE Web Server 6.1 Classloaders
Classloader
Description
Bootstrap
The Bootstrap Classloader loads all of the JDK classes. Only one instance of this classloader exists in the entire server.
System
The System Classloader loads the core Sun ONE Web Server 6.1 classes. It is created based on the classpathprefix, serverclasspath, and classpathsuffix attributes of the <JAVA> element in the server.xml file. The environment classpath is included if envclasspathignored="false" is set in the <JAVA> element. Only one instance of this classloader exists in the entire server. If any changes are made to these attributes/classes, the server must be restarted for the changes to take effect. For more information about the <JAVA> element in server.xml, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Common
The Common Classloader loads classes in the instance_dir/lib/classes directory, followed by JAR and ZIP files in the instance_dir/lib directory. The existence of these directories is optional; if they don't exist, the Common Classloader is not created. If any changes are made to these classes, the server must be restarted for the changes to take effect.
Web Application
The Web Application Classloader loads the servlets and other classes in a specific web application. That is, from WEB-INF/lib and WEB-INF/classes and from any additional classpaths specified in the extra-class-path attribute of the class-loader element in sun-web.xml. For more information, see "Classloader Elements."
An instance of this classloader is created for each web application. If dynamic reloading has been enabled, any changes made to these attributes/classes are reloaded by the server without the need for a restart. For more information, see "Dynamic Reloading of Web Applications."
JSP
The JSP Classloader loads the compiled JSP classes of JSPs. An instance of this classloader is created for each JSP file. Any changes made to a JSP are automatically detected and reloaded by the server, unless dynamic reloading of JSPs has been disabled by setting the reload-interval property to -1 in the jsp-config element of the sun-web.xml file. For more information, see "jsp-config."
The sun-web-app_2_3-1.dtd FileThe sun-web-app_2_3-1.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-1.dtd file is located in the install_dir/bin/https/dtds directory.
Note
Do not edit the sun-web-app_2_3-1.dtd file. Its contents change only with new versions of Sun ONE 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 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.
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 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 Sun ONE 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 FileThis section describes the XML elements in the sun-web.xml file. Elements are grouped as follows:
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 under each Subelements heading, unless otherwise noted.
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
Defines Sun ONE Web Server-specific configuration for a web application. 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.
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.
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-7 property Subelements
Element
Required
Description
zero or one
Contains a text description of this element.
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-8 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
Contains a text description of the parent 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.
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.
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.
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.
Attributes
none
session-manager
Specifies session manager information.
Note
As of Sun ONE Web Server 6.1, 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. 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-12 session-manager Subelements
Element
Required
Description
zero or one
Specifies session manager 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.
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-14 manager-properties Subelements
Element
Required
Description
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-15 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 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 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-16 store-properties Subelements
Element
Required
Description
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.
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-18 session-properties Subelements
Element
Required
Description
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.
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-20 cookie-properties Subelements
Element
Required
Description
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.
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.
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.
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.
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-24 default-resource-principal Subelements
Element
Required
Description
only one
Contains the name of the principal.
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
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 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." For details about JSP caching, see "JSP Cache Tags."
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.
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.
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-27 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. The table "cacheClassName Values" 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.
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-29 cache-helper Subelements
Element
Required
Description
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.
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-31 default-helper Subelements
Element
Required
Description
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.
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.
Attributes
none
url-pattern
Contains data that specifies a servlet URL pattern for which caching is enabled. See the Java 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.
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.
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.
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-37 constraint-field Subelements
Element
Required
Description
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.
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.
Classloader Elements
Classloader elements are as follows:
class-loader
Configures the classloader for the web application.
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.
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.
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-42 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
internal JDK compiler (javac)
The fully qualified class name of the Java compiler plugin 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.
To use sun.tools.javac.Main to compile JSP-generated servlets, set the javaCompilerPlugin property to org.apache.jasper.compiler.SunJavaCompiler (see also the -deprecatedjavac switch of jspc, described in "Compiling JSPs: The Command-Line Compiler").
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.2/docs/guide/intl/encoding.doc.htmlclassdebuginfo
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 in 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
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 (please 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:
Internationalization Elements
Internationalization elements are as follows:
parameter-encoding
Specifies a hidden field or default charset 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.2/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.
locale-charset-info
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 overrides the web container's default locale-to-charset mapping.
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.
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-45 locale-charset-info Attributes
Attribute
Default Value
Description
default-locale
none
Ignored in Sun ONE Web Server 6.1.
locale-charset-map
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. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
The following table provides a locale-charset-map example, listing the locale and the corresponding charset:
Alphabetical List of sun-web.xml Elements
This section provides an alphabetical list for the easy lookup of sun-web.xml elements.
Note
For a list of sun-web.xml elements by category, see "Elements in the sun-web.xml File."
Sample Web Application XML FilesThis section includes the following:
Sample web.xml File
The following is a sample web.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
-->
<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' 'http://java.sun.com/dtd/web-app_2_3.dtd'>
<web-app>
<display-name>i18n-simple</display-name>
<distributable></distributable>
<filter>
<filter-name>Simple Filter</filter-name>
<filter-class>samples.i18n.simple.servlet.SimpleFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
<init-param>
<param-name>usefilter</param-name>
<param-value>true</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Simple Filter</filter-name>
<url-pattern>/SimpleFilterServlet</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>SimpleI18nServlet</servlet-name>
<servlet-class>samples.i18n.simple.servlet.SimpleI18nServlet</servlet-class>
<load-on-startup>0</load-on-startup>
</servlet>
<servlet>
<servlet-name>IncludedServlet</servlet-name>
<servlet-class>samples.i18n.simple.servlet.IncludedServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>ForwardedServlet</servlet-name>
<servlet-class>samples.i18n.simple.servlet.ForwardedServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>SimpleFilterServlet</servlet-name>
<servlet-class>samples.i18n.simple.servlet.SimpleFilterServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>LocaleCharsetServlet</servlet-name>
<servlet-class>samples.i18n.simple.servlet.LocaleCharsetServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>SimpleI18nServlet</servlet-name>
<url-pattern>/SimpleI18nServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>IncludedServlet</servlet-name>
<url-pattern>/IncludedServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ForwardedServlet</servlet-name>
<url-pattern>/ForwardedServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>SimpleFilterServlet</servlet-name>
<url-pattern>/SimpleFilterServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>LocaleCharsetServlet</servlet-name>
<url-pattern>/LocaleCharsetServlet</url-pattern>
</servlet-mapping>
<taglib>
<taglib-uri>/i18ntaglib</taglib-uri>
<taglib-location>/WEB-INF/tlds/i18ntaglib.tld</taglib-location>
</taglib>
</web-app>Sample sun-web.xml File
The following is a sample sun-web.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
-->
<!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE
Web Server 6.1 Servlet 2.3//EN' 'http://www.sun.com/software/sunone
/webserver/dtds/sun-web-app_2_3-1.dtd'>
<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>