Configuring Web application properties

You can configure a Web application’s properties in EAServer Manager. If you have created a Web archive (WAR) file using another tool and imported it into EAServer, most properties are automatically set during the import process.

Displaying the Web Application Properties dialog box

The procedures in this section require you to start with the Web Application Properties dialog box open. Display it as follows:

1. Expand the Web Applications folder, then highlight the icon that represents your application.

2. Choose File | Web Application Properties.

General properties

General properties are as follows:

• Description An optional text description of the Web application.

• Distributable Specifies whether multiple instances of the Web application can run in a distributed server environment on different servers. If you do not select this option and run the Web application in an EAServer cluster, all requests for the Web application must go to one server in the cluster. Further configuration is required for distributed Web applications, as described in “Deploying Web applications to a cluster” in the EAServer System Administration Guide.

• Timeout This option specifies how long the server should wait for each servlet’s init method to return. For any value, no client requests are serviced while the init method is running. Service requests that arrive while init is running are blocked until init returns. Clients receive browser timeout errors when attempting to execute the servlet while init is running. You can set the Timeout value to control how the server treats servlets if the init method is still running when you shut down the server or refresh the servlet. Table 21-1 describes the possible values.

  Table 21-1: Initialization timeout values

  Value	To indicate
  -1	(The default.) init can run indefinitely, unless the server is shutdown or refreshed. If the init method is still running when the server is shutdown or refreshed, the server does not wait for init to complete before shutting down or refreshing the servlet.
  0	init can run indefinitely. Sybase does not recommend this setting, because deadlocks or other hangs in the init method can cause the server to hang when shutting down or refreshing the servlet.
  A positive integer.	The number of seconds to wait for init to return. If the init method is still running when the server is shutdown or refreshed, the server waits the specified time for init to return.

  You can override the application-wide default for individual servlets. Display the Advanced tab in the Servlet Properties window, then set the com.sybase.jaguar.servlet.init.timeout property using the syntax in Table 21-1.

• Destroy Timeout EAServer calls each servlet’s destroy method before shutting down or after you have refreshed or stopped the servlet using EAServer Manager. If service calls are still active, the Destroy Timeout setting specifies the number of seconds that the server should wait for the service calls to return before calling the destroy method. The default is 0, which specifies that EAServer calls destroy immediately.

  You can override the application-wide default for individual servlets. Display the Advanced tab in the Servlet Properties window, then set the com.sybase.jaguar.servlet.destroy.wait-time property to the desired number of seconds.

• Session Timeout This option specifies an application-wide default for the servlet Session Timeout property. Session timeouts are specified in minutes; the default is 30. A value of -1 indicates that sessions never expire. You cannot override the session timeout for individual servlets.

• Context Path The request-path prefix that clients use in URLs to access your Web application’s static content, servlets, and JSPs. For example, if you enter “estore,” users access your Web application with the prefix:

  http://host:port/estore/
  

  The default context path is the name of your Web application.

• Client Session Persistent This property determines whether the cookies used to store servlet and JSP session data is stored in persistent or temporary cookies. By default, session data is stored in temporary cookies that expire when the browser is shut down. When you select this option, EAServer sends a persistent cookie that expires when the Web application session-timeout setting expires. This property affects only the cookies that EAServer creates to store session data for the Web application (available to servlets and JSPs via request.getSession). It does not affect cookies created explicitly by servlets and JSPs.

Context initialization properties

All servlets and JSPs in a Web application share a common set of context initialization properties specified by the deployment descriptor. Servlet code can retrieve the values by calling the getInitParamers() and getInitParameterNames() methods in interface javax.Servlet.ServletContext.

Environment properties can be used for the same purpose as context-initialization properties, and allow additional datatypes besides java.lang.String. See “Environment properties” for more information.

Configuring context initialization properties

1. Display the Context Params tab in the Web Application Properties dialog box.

2. A list of properties and values appears. You can create, modify, and delete properties as follows:

   • To define a new property, click Add. Edit the Name and Value fields in the new row. You can optionally enter text in the Description field to describe the intended use.

   • To modify a property, put the cursor in the Name or Value fields, then edit the text.

   • To delete a property, put the cursor in the Name or Value fields and click Delete.

Welcome and error page specifications

You can customize the list of welcome files and error-response files in your application. These settings take effect when Web clients are browsing in your Web application’s subset of the server’s URL namespace.

Welcome files

Welcome files are used to satisfy HTTP requests that end in a directory name, rather than specifying the full path to a file or a path that is mapped to a servlet invocation. For each request that maps to a directory, the server searches the directory for files that occur in the Web application’s list of welcome files, in the listed order. For example, if the welcome-file list is “index.html, index.htm, welcome.jsp”, the server looks for index.html, then index.htm, then welcome.jsp. If the server finds a static file on the welcome-file list, the server returns its content. If a JSP on the welcome-file list exists, the server invokes the JSP. If no match exists in the directory, the server returns an HTTP 404 (file not found) error, because EAServer does not support directory listings.

Adding a welcome file

1. Display the File Refs tab in the Web Application Properties dialog box.

2. Click Add. A new row appears in the list of welcome files.

3. Place the cursor in the new row, and enter the name of the welcome file. Welcome files are plain files, without path information. You can prepend a directory separator (/), which will be ignored. For example, /index.html is the same as index.html.

Deleting a welcome file

1. Display the File Refs tab in the Web Application Properties dialog box. The welcome-file list displays.

2. Place the cursor in the row to be deleted, then click Delete.

Error pages

Error pages allow you to customize the response that the server sends to Web clients when an error occurs. You can specify HTML files to send in response to HTTP error codes and to Java exceptions thrown in JSPs or servlets. You can also define error pages at the server level. If your Web application does not specify an error page, EAServer invokes the corresponding server-level error page.

When an exception is thrown, the servlet engine will search the error page mappings for the exception and its super classes. For example, assume AException extends BException and BException extends CException and CException extends java.lang.Exception. When AException is thrown, EAServer checks if AException is mapped. If not, EAServer checks if BException is mapped, and so forth.

Adding an error page

1. Display the File Refs tab in the Web Application Properties dialog box.

2. Under Error Mapping, click Add. A new row is added to the mapping table with default settings.

3. Place the cursor in the Error/Exception cell, and type the HTTP error number or Java exception class name.

4. Place the cursor in the URL cell, and type the path to the file relative to the Web application’s context root. For example, /etc/error404.html.

5. Verify that the file exists in your EAServer installation directory and can be read by the server process. For example, the path /etc/error404.html corresponds to this file in your EAServer installation directory, where web_app is the name of the Web application:

   Repository/WebApplication/web_app/etc/error404.html
   

To set up server-level error pages, see com.sybase.jaguar.server.servlet.error-page on page 553, in the EAServer System Administration Guide.

Tag library descriptor references

JSPs can use tag libraries to serve content formatted with custom tags. The tag library is a Java class with methods to parse content that is tagged with custom tags and output formatted content to be returned in the response stream. Each tag library must have a Type Library Descriptor (TLD) file that describes the available tags and specifies the corresponding Java classes and methods.

JSPs use a type library by specifying the location of the TLD file as a URL. In your Web application, you can specify a mapping so that TLD URLs in JSPs map to a local URL. For example, you may refer to a tag library as follows in a JSP:

<%@ taglib uri="/example.tld" prefix="ex" %>

This path can be mapped to another location, such as:

/WEB-INF/tlds/PRlibrary_1_4.tld

You do not have to map TLD URLs in the Web application. If there is no mapping that matches a TLD URL, EAServer loads the file at the URL specified in the JSP and raises an error if the file does not exist.

Mapping TLD URLs provides several benefits such as:

• You can keep TLD files together in a common location.

• You can avoid multiple copies of a TLD when JSPs use different paths to refer to the same type library.

• You can code JSPs with simple paths, such as tlds/example.tld, while the actual TLD is stored in a versioned directory tree. For example, you can alias tlds/example.tld to WEB-INF/tlds/example/v1.6/example.tld. This mapping allows you to easily test new versions and roll back to previous versions if a problem occurs.

In an XML deployment descriptor, TLD URL mappings are specified by taglib elements.

Configuring TLD mappings in EAServer Manager

1. Display the Advanced tab in the Web Application Properties dialog box.

2. If necessary, add an entry for the property com.sybase.jaguar.webapplication.taglib. Otherwise, modify the existing value for this property.

3. In the property value, specify each mapping as follows:

   (taglib-uri=alias, taglib-location=real-path)
   

   Where alias is the path used in JSP source code, and real-path is the TLD file’s location relative to the Web application’s context root.

   If multiple mappings are required, separate each by a comma. For example (the following must be entered without line breaks or carriage returns):

   (taglib-uri=taglib.tld, taglib-location=TLD/abctaglib.tld),
   (taglib-uri=lib2.tld,taglib-location=TLD/lib2v2.tld)
   

Naming references

Web applications allow you to use logical names for JNDI lookups in your servlet and JSP code. Logical names allow your application to run in environments where the JNDI name space does not match the names hard coded in your application. When deploying an application, you can map the logical names to actual names that match the server’s configuration.

When developing an application, you must use JNDI to obtain database connections, mail sessions, and EJB proxies. You must catalog the JNDI names used by your code in the application’s deployment descriptor.

All logical JNDI names used in your application must be prefixed with java:comp/env. The J2EE specification requires the following hierarchy, based on resource type:

• java:comp/env/ejb for EJB references

• java:comp/env/jdbc for JDBC javax.sql.DataSource references

• java:comp/env/mail for JavaMail session references

• java:com/env/url for java.net.URL references

• java:com/env/jms for javax.jms references

EJB references

Servlets and JSPs use EJB references to instantiate proxies for EJB home interfaces. See Chapter 8, “Creating Enterprise JavaBeans Clients,” for more information. EJB references must be cataloged in the deployment descriptor so that the Web application can run independent of a specific naming configuration. When deploying the Web application, a site administrator can specify site-specific EJB JNDI names.

Servlets and JSPs can look up an EJB by specifying the reference name prefixed with java:comp/env/. For example, if you enter ejb/catalog in EAServer Manager, use java:comp/env/ejb/catalog in your JSP or servlet source code.

To add or configure an EJB reference, open the Web Application Properties dialog box.

Adding an EJB reference

1. Display the EJB References tab.

2. Click Add. A reference with default settings is created. Edit the settings as described below.

Editing an EJB reference

1. If necessary, display the EJB References tab. Existing references are displayed as a list with one row for each reference.

2. Edit the reference fields of interest as follows:

   • Name Specifies the JNDI name used in your code to refer to the called EJB. The aliased name is displayed in the Link Value field. Enter the part of the JNDI name that begins with ejb/. For example, if your code refers to java:comp/env/ejb/MyBean, enter ejb/MyBean.

   • Type Choose Session for session Beans or Entity for entity Beans.

   • Home The Java class name of the EJB home interface, specified in dot notation. For example, com.sybase.MyBeanHome.

   • Remote The Java class name of the EJB remote interface, specified in dot notation. For example, com.sybase.MyBeanRemote.

   • Link Value The actual JNDI name EJB component that is installed in the server where your component, Web application, or application client is to be deployed. This must match the JNDI name property in the Component Properties of the called EJB component.

     For invocations of components on remote servers, you can also specify a corbaname interoperable naming URL, as described in “Interoperable naming URLs”.

3. To delete a reference, click anywhere in the fields for the reference of interest and click Delete.

EJB local references

To access an EJB’s local interface, define an EJB local reference. Local interfaces are available only to EJB components, Java servlets, and JSPs hosted on the same server as the target component.

Adding an EJB local reference

1. Display the EJB Local References tab.

2. Click Add. A reference with default settings is created. Edit the settings as described below.

Editing an EJB local reference

1. If necessary, display the EJB Local References tab. Existing references are displayed as a list with one row for each reference.

2. Edit the reference fields of interest as follows:

   • Name Specifies the JNDI name used in your code to refer to the called EJB. The aliased name is displayed in the Link Value field. Enter the part of the JNDI name that begins with ejb/. For example, if your code refers to java:comp/env/ejb/MyBean, enter ejb/MyBeanLocal.

   • Type Choose Session for session Beans or Entity for entity Beans.

   • Home The Java class name of the EJB local home interface, specified in dot notation. For example, com.sybase.MyBeanLocalHome.

   • Local The Java class name of the EJB local interface, specified in dot notation. For example, com.sybase.MyBeanLocal.

   • Link Value The actual JNDI name of the EJB component that is installed in the server where your component or Web application is to be deployed. This is specified by the JNDI Name property in the Component Properties of the called EJB component.

3. To delete a reference, click anywhere in the fields for the reference of interest and click Delete.

Resource references

Resource references are used to obtain connector and database connections, and to access JMS connection factories, JavaMail sessions, and URL links.

To add or configure a resource reference, open the Web Application Properties dialog box.

Adding a resource reference

1. Display the Resource References tab.

2. Click Add. A reference with default settings is created. Edit the settings as described below.

Editing a resource reference

1. If necessary, display the Resource References tab. Existing references are displayed as a list with one row for each reference.

2. Edit the reference fields of interest as follows:

   • Name The partial JNDI name used in servlet and JSP code. Use the prefix mail/ for JavaMail references, jdbc/ for data source references, url/ for java.net.URL references, and jms/ for javax.jms references. For example, if your code refers to java:comp/env/jdbc/MyDatabase, enter jdbc/MyDatabase.

   • Type Choose the type of resource:

     • javax.sql.DataSource for JDBC connections. See “JDBC DataSource lookup” for more information.

     • java.mail.Session for JavaMail sessions. See Chapter 35, “Creating JavaMail,” for more information.

     • java.net.url for aliased URLs.

     • javax.jms.QueueConnectionFactory for JMS queue connection factories. See “Looking up a ConnectionFactory object” for more information.

     • javax.jms.TopicConnectionFactory for JMS topic connection factories. See “Looking up a ConnectionFactory object” for more information.

   • Sharing Scope Choose Sharable or Unsharable. By default, connections to a resource manager are sharable across EJBs in an application that use the same resource in the same transaction context.

     This is available only to Web applications and EJB components.

   • Authentication Select the source of the authentication credentials:

     • Application – use the credentials configured for the connection cache.

     • Container – use the credentials of the caller who logged in to EAServer and created the component instance.

   • Resource Link Specify the resource link for the resource type:

     • javax.sql.DataSource – select the name of the EAServer connection cache or connector to be used for this resource.

     • java.mail.Session – specify the SMTP mail server for outgoing mail.

     • java.net.url – enter the URL string, as it would be used to construct a java.net.URL instance by calling the URL(java.lang.String) constructor. URLs must contain a protocol and host address, for example: http://www.sybase.com or ftp://pub.sybase.com.

     • javax.jms.QueueConnectionFactory – select the name of the queue connection factory.

     • javax.jms.TopicConnectionFactory – select the name of the topic connection factory.

3. To delete a resource reference, click anywhere in the fields for the resource reference of interest and click Delete.

Resource environment references

Resource environment references are logical names applied to objects administered by EAServer, which can be accessed by Web applications, application clients, and EJB components.

To add or configure a resource environment reference, open the Web Application Properties dialog box.

Adding a resource environment reference

1. Display the Resource Environment References tab.

2. Click Add. A reference with default settings is created. Edit the settings as described below.

Editing a resource environment reference

1. If necessary, display the Resource Environment References tab. Existing references are displayed as a list with one row for each reference.

2. Edit the reference fields of interest as follows:

   • Name The partial JNDI name used in servlet and JSP code. Use the prefix jms/ for JMS reference. For example, if your code refers to java:comp/env/jms/MyQueue, enter jms/MyQueue.

   • Type Choose the type of resource:

     • javax.jms.Queue for JMS message queues.

     • java.jms.Topic for JMS message topics.

   • Link Value If the resource type is javax.jms.Queue, enter the name of a configured queue; if the resource type is javax.jms.Topic, enter the name of a configured topic.

3. To delete a resource environment reference, click anywhere in the fields for the reference of interest and click Delete.

Environment properties

Environment properties allow you to specify global read-only data for use by servlets and JSPs in the Web application.

Servlets and JSPs must use JNDI to retrieve environment properties, using the prefix java:comp/env in JNDI lookups. Unlike context initialization properties, environment properties can have datatypes other than java.lang.String.

The deployment descriptor catalogs the environment properties used by your servlets and JSPs, as well as each property’s Java datatype and default value. Deployers can tailor the values to match a server’s configuration. For example, you may have environment properties to specify the name of a logging file, or to tune cache usage.

To add or configure an environment property, open the Web Application Properties dialog box.

Adding an environment property

1. Display the Environment tab.

2. Click Add. EAServer Manager creates a new entry with default settings. Edit the settings as described below:

Editing an environment property

1. If necessary, display the Environment tab. A list of environment properties appears.

2. Edit the fields for the property of interest:

   • Entry The environment property’s JNDI name, relative to the java:comp/env prefix.

   • Type Choose the Java datatype that matches the property value from the dropdown list.

   • Value The initial or post-deployment value of the property, specified as text in a format that is valid for the specified datatype.

   • Description Optionally enter a comment to explain how the property is used.

Request path mappings

Your application’s deployment descriptor must specify the request path mappings for the application’s servlets and JSPs. You can map full paths, partial paths, or file extensions to servlets. Path mappings are specified relative to the application’s root request path.

To map request paths to a JSP, the JSP must be defined in EAServer Manager as a Web component. See Chapter 24, “Creating JavaServer Pages,” for more information.

EAServer uses the precedence rules defined in the Servlet 2.3 specification to evaluate each URL:

1. EAServer checks whether a mapping uses the exact path.

2. EAServer checks whether a directory in the path is mapped to a servlet, starting at the most deeply nested directory in the path, and working back using the forward-slash character (/) as a separator. For example, if the application’s root request path is MyApp and the URL path is MyApp/Accounts/Manage/add.jsp, EAServer checks for servlets mapped to /Accounts/Manage, then /Accounts.

3. If the last node in the path contains an extension, EAServer checks for a servlet mapped to that file extension. A file extension is defined as the part of the URL that follows a ‘.’ occurring after the last ‘/’ in the URL. For example, in the path MyApp/Accounts/Manage/add.calc, the extension is calc.

4. If neither of the previous two rules results in a match, EAServer invokes the application’s default servlet if defined. The default servlet is mapped to the path /. If no default servlet is defined, EAServer looks for a static file matching the path.

Adding a request path mapping

1. Display the Servlet Mapping tab in the Web Application Properties dialog box.

2. Click Add. A new mapping appears with default settings. Edit the settings as described below.

Editing a request path mapping

1. If necessary, display the Servlet Name tab in the Web Application Properties dialog box. A list of mappings appears, formatted as a table. You can edit any mapping by editing the text directly within the table cells.

2. Edit the servlet name and mapped path, using the following rules to format the path specification:

   • All mappings are relative to the Web application’s root request directory.

   • To map a directory, enter a path that ends in a ‘*’, for example /foo/* or /foo/stuff/*.

   • To map an extension, enter *.ext, where ext is the extension.

   • To specify a default servlet for the application, enter the path as a single forward slash (/).

   • To specify an exact match, enter the full path relative to the Web application’s root request directory.

MIME mappings

A file’s MIME type specifies how a server or browser should interpret the file. For example, whether the file contains plain text, formatted HTML, an image, or a sound recording. In a Web server, MIME mappings specify how a static file should be interpreted by mapping file extensions to MIME types. MIME mappings affect only static files. Servlets and JSPs must be coded to specify a MIME type for their response.

For more information on MIME types, visit:

http://www.oac.uci.edu/indiv/ehood/MIME/MIME.html

EAServer includes preconfigured MIME mappings that you can customize using your Web application’s properties. Web application MIME mappings override EAServer’s preconfigured mappings.

Adding a MIME mapping

1. Display the MIME Mapping tab in the Web Application Properties dialog box.

2. Click Add.

Editing a MIME mapping

1. If necessary, display the MIME Mapping tab in the Web Application Properties dialog box. The configured mappings display.

2. Edit the fields as appropriate:

   • Extension The file extension for files of this type.

   • MIME Type The MIME specification, for example, text/plain or text/sgml.

JAXP properties

Configures the default JAXP, DOM, and XSLT parser implementations used by the Web application. See Chapter 36, “Configuring Java XML Parser Support,” for more information on these properties.

Java Classes properties

The Java Classes tab allows you to add classes and JAR files to the Web application’s custom class list. The custom class list specifies which Java classes must be reloaded when the Web application is refreshed. Chapter 30, “Configuring Custom Java Class Lists,” describes how to configure this setting.

Extensions properties

The Extensions tab in the Web Application properties dialog box configures dependencies on Java extensions. These settings provide a mechanism to formally declare the Java extensions required by the Web application, and to verify that required extensions are available in EAServer. “Using Java extensions” describes these settings in detail.

Additional files

The Additional Files tab in the Web Application properties dialog box configures the com.sybase.jaguar.webapplication.files property, which specifies additional files that are to be archived when the Web application is exported or replicated to another server with the synchronize feature. By default, the file set includes the Web application’s context root directory and its contents.

The rules for setting this property are the same as for the com.sybase.jaguar.component.files component property. See “Component properties: Additional Files” for more information.

Security properties

Configures user authentication for the Web application and allows you to configure authorized access to URLs served by the Web application. Chapter 3, “Using Web Application Security,” in the EAServer Security Administration and Programming Guide describes how to configure these properties.

Page Caching properties

You can use dynamic page caching to improve the response time for servlets and JSPs in your Web application. The properties on this tab allow you to configure default caching options for Web components that have caching enabled. For more information, see “Dynamic page caching” in Chapter 5, “Web Application Tuning,” in the EAServer Performance and Tuning Guide.

Listener properties

EAServer’s implementation of application lifecycle events enables you to register event listeners that can respond to state changes in a Web application’s ServletContext and HttpSession objects. See “Application lifecycle event listeners” for more information.

Adding a listener

1. Display the Listeners tab in the Web Application Properties dialog box.

2. Click Add. This adds a new row to the list of Listeners.

3. Enter the listener class name.

4. To modify the order in which EAServer notifies the listeners, highlight a listener name and click Move Up or Move Down until it is positioned correctly.

Filter Mapping properties

A filter is a Java class that is called to process client requests or the server’s response. Filters can be used to modify the request header or the content of a servlet request or response. Chapter 23, “Using Filters and Event Listeners,” describes how to create filters.

Filters can be mapped to a URL or a servlet name. When a filter is mapped to a URL (path-mapped), the filter applies to every servlet and JSP in the Web application. When a filter is mapped to a servlet name (servlet-mapped), it applies to a single servlet or JSP. The path-mapped filters are executed first, followed by the servlet-mapped filters.

Mapping a filter

1. Display the Filter Mapping tab in the Web Application Properties dialog box.

2. Click Add. This adds a new row to the Filter Mapping list.

3. Enter the filter properties:

   • Filter – logical name for the filter.

   • Target – servlet class name or the URL string.

   • Target Type – choose either Servlet Name or URL Pattern.

   • Description – brief description of the filter’s purpose.

Copyright © 2005. Sybase Inc. All rights reserved.