Chapter 19 Creating Web Applications

Configuring Web application properties

You can configure a Web application's properties in Jaguar 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.

Steps 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:

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.

Steps 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:

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

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

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

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.

Steps 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

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:

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

Note   Tag library classes A Web application's tag library classes must be deployed in the WEB-INF/lib or WEB-INF/classes directories, with the other Java classes required by your Web application. See "Java classes" for more information.

Steps Configuring TLD mappings in Jaguar Manager

  1. Display the All Properties 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:

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

Note   The EJB References tab configuration is the same for Web applications, application clients, and EJB components.

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

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

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

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

Note   The Resource References tab configuration is the same for Web applications, application clients, and EJB components.

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

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

Note   The Resource Environment References tab configuration is the same for Web applications, application clients, and EJB components.

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

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

Note   The Environment tab configuration is the same for Web applications, application clients, and EJB components.

Steps Adding an environment property

  1. Display the Environment tab.
  2. Click Add. Jaguar Manager creates a new entry with default settings. Edit the settings as described below:

Steps 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:

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 Jaguar Manager as a Web component. See Chapter 22, "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.

Note   Implicit JSP mapping The jsp extension is implicitly mapped to invoke EAServer's JSP engine. You can override this mapping in the explicit mappings for your Web application by mapping *.jsp to a servlet or JSP. However, if you do so, there is no way to invoke the EAServer JSP engine to compile and run arbitrary JSP files. Explicit *.jsp mappings are not recommended.

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

Steps 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:

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.

Steps Adding a MIME mapping

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

Steps 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:

JAXP properties

Configures the default JAXP, DOM, and XSLT parser implementations used by the Web application. See Chapter 27, "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 28, "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. The EAServer Security Administration and Programming guide describes how to configure security for your Web application.

Page Caching properties

You can configure page caching for a Web application, as well as for a Web component. EAServer first checks the component-level page caching properties, and if none exists, checks the application-level properties. "Page caching" describes how to configure page caching for a Web component.

Steps Configuring page caching for a Web application

  1. Display the Page Caching tab in the Web Application Properties dialog box.
  2. Optionally, edit the timeout value, and enter the parameters that you want to use in the key. The parameters you enter here are the default settings for all the servlets and JSPs in the Web application. See Table 20-2 for a description of the page caching properties.

Note   By default, page caching is disabled, and you cannot enable page caching at the Web application-level.

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.

Steps 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 21, "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.

Steps 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:

 

Copyright © 2002 Sybase, Inc. All rights reserved.