Chapter 22 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 Jaguar, most properties are automatically set during the import process.

To display 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 a Jaguar 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 "Configuring a distributed Web application".
• Timeout This option specifies how long the Jaguar server should wait for each servlet's init method to return. The timeout period is measured in seconds. The default is 0, which indicates that there is no time limit.
  You can override the application-wide default for individual servlets. Display the All Properties tab in the Servlet Properties window, then set the com.sybase.jaguar.servlet.init.timeout property to the desired number of seconds.
  
  If a servlet's init method might run indefinitely, specify a finite timeout period. If the init method does not return during the specified timeout period, the server abandons the servlet and the servlet will not be available until the server is restarted or refreshed. Service requests that arrive while init is running are blocked until init returns. If init is allowed to run indefinitely, clients receive browser timeout errors when attempting to execute the servlet.
  
• Destroy Timeout Jaguar calls each servlet's destroy method before shutting down or after you have refreshed or stopped the servlet using Jaguar 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 Jaguar calls destroy immediately.
  You can override the application-wide default for individual servlets. Display the All Properties 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 of 0 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 Persistence 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. To use persistent cookies in your Web application, set the following property on the All Properties tab in the Web Application Properties dialog box:

  com.sybase.jaguar.webapplication.cookie.persistence

  
  When this property is false (the default), Jaguar stores session data in temporary cookies. When set to true, Jaguar sends a persistent cookie that expires when the Web application session-timeout setting expires. This property affects only the cookies that Jaguar 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.

To configure 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 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 Jaguar does not support directory listings.

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

To delete 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, 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, Jaguar checks if AException is mapped. If not, Jaguar checks if BException is mapped, and so forth.

To add 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 Jaguar installation directory and can be read by the Jaguar server process. For example, the path /etc/error404.html corresponds to this file in your Jaguar 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, Jaguar 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.

   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.

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

EJB references

Servlets and JSPs use EJB references to instantiate proxies for EJB home interfaces. See Chapter 8, "Creating Enterprise JavaBean Clients," in the Jaguar CTS Programmer's Guide 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 home 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 an EJB reference:

1. Display the EJB References tab in the Web Application Properties dialog box.
   
   
2. Click Add. A reference with default settings is created. Edit the settings as described below.
   
   

To edit an EJB reference:

1. If necessary, display the EJB References tab in the Web Application Properties dialog box. 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 EJB's 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 home interface, specified in dot notation. For example, com.sybase.MyBeanRemote .
   • Link Value The actual JNDI name of an instance of the specified EJB that is installed in the Jaguar server where your EJB is to be deployed. This is specified by the Home 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 database connections and JavaMail sessions.

To add a resource reference:

1. Display the Resource References tab in the Web Application Properties dialog box.
   
   
2. Click Add. A reference with default settings is created. Edit the settings as described below.
   
   

To edit a resource reference:

1. If necessary, display the Resource References tab in the Web Application Properties dialog box. 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, and url/ for java.net.URL 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 30, "Creating JavaMail" for more information.
     • java.net.url for aliased URLs.
   • Authentication Container is the only option that is supported.
   
   
   
3. Specify deployment properties:
   • SMTP Host For JavaMail resources. Specifies the SMTP mail server for outgoing mail.
   • Connection Cache For JDBC references. The name of the Jaguar connection cache to be used for this reference.
   • URL Specification For aliased URLs. 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 .
   
   
   

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 an environment property:

1. Display the Environment tab in the Web Application Properties dialog box.
   
   
2. Click Add. Jaguar Manager creates a new entry with default setttings. Edit the settings as described below:
   
   

To edit environment properties:

1. If necessary, display the Environment tab in the Web Application Properties dialog box. 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 Jaguar Manager as a Web component. See Chapter 24, "JavaServer Pages" for more information.

Jaguar uses the precedence rules defined in the Servlet 2.2 specification to evaluate each URL:

1. Jaguar checks whether a mapping uses the exact path.
2. Jaguar 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, Jaguar checks for servlets mapped to /Accounts/Manage, then /Accounts.
3. If the last node in the path contains an extension, Jaguar checks for a servlet mapped to that file extension. A file extension is defined as the part of the URL that follows a '.' occuring 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, Jaguar invokes the application's default servlet if defined. The default servlet is mapped to the path /. If no default servlet is defined, Jaguar looks for a static file matching the path.

   Implicit JSP mapping The jsp extension is implicitly mapped to invoke Jaguar's JSP engine. You can override this mapping in the explicit mappings for your Web application.

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

To edit 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

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

To add a MIME mapping:

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

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

Security properties

Chapter 25, "Configuring Web Application Security" describes how to configure security for your Web application.

Copyright © 2000 Sybase, Inc. All rights reserved.