Configuring Web Application Components

 

The following sections describe how to configure Web Application components:

• Configuring Servlets

• Configuring JSP

• Configuring JSP Tag Libraries

• Configuring Welcome Pages

• Setting Up a Default Servlet

• Customizing HTTP Error Responses

• Using CGI with WebLogic Server

• Serving Resources from the CLASSPATH with the ClasspathServlet

• Configuring External Resources in a Web Application

• Referencing EJBs in a Web Application

• Determining the Encoding of an HTTP Request

• Mapping IANA Character Sets to Java Character Sets

 

---

Configuring Servlets

Servlets are registered and configured as a part of a Web Application. To register a servlet, you add several entries to the Web Application deployment descriptor. The first entry, under the <servlet> element, defines a name for the servlet and specifies the compiled class that executes the servlet. (Or, instead of specifying a servlet class, you can specify a JSP page.) This element also contains definitions for initialization parameters and security roles for the servlet. The second entry, under the <servlet-mapping> element, defines the URL pattern that calls this servlet.

For complete instructions on editing the Web Application deployment descriptor, see:

• Step 9: Deploy Servlets

• Step 10: Map a servlet to a URL

Servlet Mapping

Servlet mapping controls how you access a servlet. The following examples demonstrate how you can use servlet mapping in your Web Application. In the examples, a set of servlet configurations and mappings (from the web.xml deployment descriptor) is followed by a table (see url-patterns and Servlet Invocation) showing the URLs used to invoke these servlets.

Listing 3-1 Servlet Mapping Example

<servlet>
  <servlet-name>watermelon</servlet-name>
  <servlet-class>myservlets.watermelon</servlet-class>
</servlet>

<servlet>
  <servlet-name>garden</servlet-name>
  <servlet-class>myservlets.garden</servlet-class>
</servlet>

<servlet>
  <servlet-name>list</servlet-name>
  <servlet-class>myservlets.list</servlet-class>
</servlet>

<servlet>
  <servlet-name>kiwi</servlet-name>
  <servlet-class>myservlets.kiwi</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>watermelon</servlet-name>
  <url-pattern>/fruit/summer/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
  <servlet-name>garden</servlet-name>
  <url-pattern>/seeds/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
  <servlet-name>list</servlet-name>
  <url-pattern>/seedlist</url-pattern>
</servlet-mapping>

<servlet-mapping>
  <servlet-name>kiwi</servlet-name>
  <url-pattern>*.abc</url-pattern>
</servlet-mapping>

Table 3-1 url-patterns and Servlet Invocation

URL	Servlet Invoked
http://host:port/mywebapp/fruit/summer/index.html	watermelon
http://host:port/mywebapp/fruit/summer/index.abc	watermelon
http://host:port/mywebapp/seedlist	list
http://host:port/mywebapp/seedlist/index.html	The default servlet, if configured, or an HTTP 404 File Not Found error message. If the mapping for the list servlet had been /seedlist*, the list servlet would be invoked.
http://host:port/mywebapp/seedlist/pear.abc	kiwi If the mapping for the list servlet had been /seedlist*, the list servlet would be invoked.
http://host:port/mywebapp/seeds	garden
http://host:port/mywebapp/seeds/index.html	garden
http://host:port/mywebapp/index.abc	kiwi

Servlet Initialization Parameters

You define initialization parameters for servlets in the Web Application deployment descriptor, in the <init-param> element of the <servlet> element, using <param-name> and <param-value> tags. For example:

Listing 3-2 Example of Configuring Servlet Initialization Parameters

<servlet>
  <servlet-name>HelloWorld2</servlet-name> 
  <servlet-class>examples.servlets.HelloWorld2</servlet-class>

  <init-param>
    <param-name>greeting</param-name> 
    <param-value>Welcome</param-value> 
  </init-param>

  <init-param>
    <param-name>person</param-name> 
    <param-value>WebLogic Developer</param-value> 
  </init-param>
</servlet>

For more information on editing the Web Application deployment descriptor, see Writing Web Application Deployment Descriptors.

 

---

Configuring JSP

You deploy JavaServer Pages (JSP) files by placing them in the root (or in a subdirectory below the root) of a Web Application. Additional JSP configuration parameters are defined in the <jsp-descriptor> element of the WebLogic-specific deployment descriptor, weblogic.xml. These parameters define the following functionality:

• Options for the JSP compiler

• Debugging

• How often WebLogic Server checks for updated JSPs that need to be recompiled

• Character encoding

For a complete description of these parameters, see JSP Parameter Names and Values.

For instructions on editing the weblogic.xml file, see Main Steps to Create the weblogic.xml File.

You can also register a JSP as a servlet using the <servlet> tag. In this example a URL containing /main will invoke myJSPfile.jsp:

<servlet>
     <servlet-name>myFoo</servlet-name>
     <jsp-file>myJSPfile.jsp</jsp-file>
</servlet>

<servlet-mapping>
     <servlet-name>myFoo</servlet-name>
     <url-pattern>/main</url-pattern>
</servlet-mapping>

Registering a JSP in this manner allows you to specify the load order, initialization parameters, and security roles for a JSP, just as you would for a servlet.

 

---

Configuring JSP Tag Libraries

Weblogic Server provides the ability to create and use custom JSP tags. Custom JSP tags are Java classes that can be called from within a JSP page. To create custom JSP tags, you place them in a tag library and define their behavior in a tag library descriptor (TLD) file. This TLD must be made available to the Web Application containing the JSP by defining it in the Web Application deployment descriptor. It is a good idea to place the TLD file in the WEB-INF directory of your Web Application, because that directory is never available publicly.

In the Web Application deployment descriptor, you define a URI pattern for the tag library. This URI pattern must match the value in the taglib directive in your JSP pages. You also define the location of the TLD. For example, if the taglib directive in the JSP page is:

<%@ taglib uri="myTaglib" prefix="taglib" %>

and the TLD is located in the WEB-INF directory of your Web Application, you would create the following entry in the Web Application deployment descriptor:

<taglib>
   <taglib-uri>myTaglib</taglib-uri>
   <tablig-location>WEB-INF/myTLD.tld</taglib-location>
</taglib>

You can also deploy a tag library as a .jar file. For more information, see Deploying a JSP Tag Library as a JAR File.

For more information on creating custom JSP tag libraries, see Programming JSP Tag Extensions.

WebLogic Server also includes several custom JSP tags that you can use in your applications. These tags perform caching, facilitate query parameter-based flow control, and facilitate iterations over sets of objects. For more information, see:

• Using Custom WebLogic JSP Tags.

• Using WebLogic JSP Form Validation Tags.

 

---

Configuring Welcome Pages

WebLogic Server allows you to set a page that is served by default if the requested URL is a directory. This feature can make your site easier to use, because the user can type a URL without giving a specific filename.

Welcome pages are defined at the Web Application level. If your server is hosting multiple Web Applications, you need to define welcome pages separately for each Web Application.

To define Welcome pages, edit the Web Application deployment descriptor, web.xml. For more information, see Step 13: Define welcome pages

If you do not define Welcome Pages, WebLogic Server looks for the following files in the following order and serves the first one it finds:

1. index.html

2. index.htm

3. index.jsp

For more information, see How WebLogic Server Resolves HTTP Requests.

 

---

Setting Up a Default Servlet

Each Web Application has a default servlet. This default servlet can be a servlet that you specify, or, if you do not specify a default servlet, WebLogic Server uses an internal servlet called the FileServlet as the default servlet. For more information on the FileServlet, see How WebLogic Server Resolves HTTP Requests.

You can register any servlet as the default servlet. Writing your own default servlet allows you to use your own logic to decide how to handle a request that falls back to the default servlet.

Setting up a default servlet replaces the FileServlet and should be done carefully because the FileServlet is used to serve most files, such as text files, HTML file, image files, and more. If you expect your default servlet to serve such files, you will need to write that functionality into your default servlet.

To set up a user-defined default servlet:

1. Define your servlet as described in Configuring Servlets.

2. Map your default servlet with a url-pattern of "/". This causes your default servlet to respond to all types of files except for those with extensions of *.htm or *.html, which are internally mapped to the FileServlet.

   If you also want your default servlet to respond to files ending in *.htm or *.html, then you must map those extensions to your default servlet, in addition to mapping "/". For instructions on mapping servlets, see Configuring Servlets.

3. If you still want the FileServlet to serve files with other extensions:

   1. Define a servlet and give it a <servlet-name>, for example myFileServlet.

   2. Define the <servlet-class> as weblogic.servlet.FileServlet.

   3. Using the <servlet-mapping> element, map file extensions to the myFileServlet (in addition to the mappings for your default servlet). For example, if you want the myFileServlet to serve gif files, map *.gif to the myFileServlet.

Note: The FileServlet includes the SERVLET_PATH when determining the source filename if docHome is not specified. As a result, it is possible to explicitly server only files from specific directories by mapping the FileServlet to /dir/*, etc.

 

---

Customizing HTTP Error Responses

You can configure WebLogic Server to respond with your own custom Web pages or other HTTP resources when particular HTTP errors or Java exceptions occur, instead of responding with the standard WebLogic Server error response pages.

You define custom error pages in the <error-page> element of the Web Application deployment descriptor (web.xml). For more information on error pages, see error-page Element.

 

---

Using CGI with WebLogic Server

WebLogic Server provides functionality to support your legacy Common Gateway Interface (CGI) scripts. For new projects, we suggest you use HTTP servlets or JavaServer Pages.

WebLogic Server supports all CGI scripts through an internal WebLogic servlet called the CGIServlet. To use CGI, register the CGIServlet in the Web Application deployment descriptor (see Sample Web Application Deployment Descriptor Entries for Registering the CGIServlet). For more information, see Configuring Servlets.

Note: It is important to note that a CGI script cannot be served by CGIServlet if the script filename does not have an extension. Filename extensions are required.

Configuring WebLogic Server to use CGI

To configure CGI in WebLogic Server:

1. Declare the CGIServlet in your Web Application by using the <servlet> and <servlet-mapping> elements. The class name for the CGIServlet is weblogic.servlet.CGIServlet. You do not need to package this class in your Web Application.

2. Register the following initialization parameters for the CGIServlet by defining the following <init-param> elements:

   cgiDir

   The path to the directory containing your CGI scripts. You can specify multiple directories, separated by a ";" (Windows) or a ":" (Unix). Specify cgiDir if you want your CGI directory to be relative to the app-root or located inside a WAR file. Note the following about cgiDir:

   You must specify each and every directory that contains a CGI script so that WebLogic Server can extract it.

   The CGIServlet does not extract subdirectories from cgiDir paths.

   All CGI script names must be unique regardless of subdirectory location since they are all extracted into the same directory and/or they are searched for using the script name and not their full or relative path.

   For example: /foo/myscript.pl and /bar/myscript.pl will be confused and it is undetermined which one will be invoked.

   useByteStream

   The alternate to using the default Char streams for data transfer, this parameter, which is case sensitive, will allow the use of images in the CGI servlet without distortion.

   extension mapping

   Maps a file extension to the interpreter or executable that runs the script. If the script does not require an executable, this initialization parameter may be omitted.

   The <param-name> for extension mappings must begin with an asterisk followed by a dot, followed by the file extension, for example, *.pl.

   The <param-value> contains the path to the interpreter or executable that runs the script You can create multiple mappings by creating a separate <init-param> element for each mapping.

Listing 3-3 Sample Web Application Deployment Descriptor Entries for Registering the CGIServlet

<servlet>
 <servlet-name>CGIServlet</servlet-name>
 <servlet-class>weblogic.servlet.CGIServlet</servlet-class>
 <init-param>
  <param-name>cgiDir</param-name>
  <param-value>
   /bea/wlserver6.0/config/mydomain/applications/myWebApp/cgi-bin
  </param-value>
 </init-param>

  <init-param>
   <param-name>*.pl</param-name>
   <param-value>/bin/perl.exe</param-value>
  </init-param>
</servlet>

...

<servlet-mapping>
   <servlet-name>CGIServlet</servlet-name>
   <url-pattern>/cgi-bin/*</url-pattern>
</servlet-mapping>

Requesting a CGI Script

The URL used to request a perl script must follow the pattern:

http://host:port/myWebApp/cgi-bin/myscript.pl

Where

host:port

Is the host name and port number of WebLogic Server.

myWebApp

is the name of your Web Application.

cgi-bin

is the url-pattern name mapped to the CGIServlet.

myscript.pl

is the name of the Perl script that is located in the directory specified by the cgiDir initialization parameter.

 

---

Serving Resources from the CLASSPATH with the ClasspathServlet

If you need to serve classes or other resources from the system CLASSPATH, or from the WEB-INF/classes directory of a Web Application, you can use a special servlet called the ClasspathServlet. The ClasspathServlet is useful for applications that use applets or RMI clients and require access to server-side classes. The ClasspathServlet is implicitly registered and available from any application.

The general form for invoking the ClasspathServlet is:

http://server:port[/<context-path>]/classes[/<app>@[<webapp.]]/
<package>.<classname>>.class

where

context-path

specifies the application for which ClasspathServlet is invoked.

app

is the name of the application that contains the classes (or contains the Web application that contains the classes) to be served.

webapp

is the name of the Web application that contains the classes.

There are two ways that you can use the ClasspathServlet:

• To serve a resource from the system CLASSPATH, call the resource with a URL such as:

  http://server:port/classes/weblogic/myClass.class
  

• To serve a resource from the WEB-INF/classes directory of a Web Application, call the resource with a URL such as:

  http://server:port/classes/myApp@myWebApp/examples/servlets/myC
  lass.class
  

  In this case, the resource is located in the following directory, relative to the root of the Web Application:

  WEB-INF/classes/my/resource/myClass.class
  

disableStrictCheck relaxes the restriction of the download file type. When disableStrictCheck is set to false, ClasspathServlet only allows downloads of .class files, .war files, .jar files, .ear files, .rar files and .mf files.

To access an applet or another similar file, set disableStrictCheck to true.

Warning: Since the ClasspathServlet serves any resource located in the system CLASSPATH, do not place resources that should not be publicly available in the system CLASSPATH.

 

---

Configuring External Resources in a Web Application

When accessing external resources, such as a DataSource from a Web Application via JNDI, you can map the JNDI name you look up in your code to the actual JNDI name as bound in the JNDI tree. This mapping is made using both the web.xml and weblogic.xml deployment descriptors and allows you to change these resources without changing your application code. You provide a name that is used in your Java code, the name of the resource as bound in the JNDI tree, and the Java type of the resource, and you indicate whether security for the resource is handled programmatically by the servlet or from the credentials associated with the HTTP request.

To configure external resources:

1. Enter the resource name in the deployment descriptor as you use it in your code, the Java type, and the security authorization type. For instructions on making deployment descriptor entries, see Step 16: Reference external resources.

2. Map the resource name to the JNDI name. For instructions on making deployment descriptor entries, see Step 3 Map resources to JNDI.

This example assumes that you have defined a data source called accountDataSource. For more information, see JDBC Data Sources.

Listing 3-4 Example of Using a DataSource

Servlet code: 
javax.sql.DataSource ds = (javax.sql.DataSource) ctx.lookup
                           ("myDataSource");

web.xml entries:

<resource-ref>
. . .
   <res-ref-name>myDataSource</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>CONTAINER</res-auth>
. . .
</resource-ref>

weblogic.xml entries:

<resource-description>
   <res-ref-name>myDataSource</res-ref-name>
   <jndi-name>accountDataSource</jndi-name>
</resource-description>

 

---

Referencing EJBs in a Web Application

You can reference EJBs in a Web Application by giving them a name in the Web Application deployment descriptor that is mapped to the JNDI name for the EJB that is defined in the weblogic-ejb-jar.xml file deployment descriptor. This procedure provides a level of indirection between the Web Application and an EJB and is useful if you are using third-party EJBs or Web Applications and cannot modify the code to directly call an EJB. In most situations, you can call the EJB directly without using this indirection. For more information, see Invoking Deployed EJBs.

To reference an EJB for use in a Web Application:

1. Enter the EJB reference name you use to look up the EJB in your code, the Java class name, and the class name of the home and remote interfaces of the EJB in the <ejb-ref> element of the Web Application deployment descriptor. For instructions on making deployment descriptor entries, see Step 21: Reference Enterprise JavaBean (EJB) resources

2. Map the reference name in <ejb-reference-description> element of the WebLogic-specific deployment descriptor, weblogic.xml, to the JNDI name defined in the weblogic-ejb-jar.xml file. For instructions on making deployment descriptor entries, see Step 3 Map resources to JNDI.

   If the Web Application is part of an Enterprise Application Archive (.ear file), you can reference an EJB by the name used in the .ear with the <ejb-link> element.

 

---

Determining the Encoding of an HTTP Request

WebLogic Server needs to convert character data contained in an HTTP request from its native encoding to the Unicode encoding used by the Java servlet API. In order to perform this conversion, WebLogic Server needs to know which codeset was used to encode the request.

There are two ways you can define the codeset:

• For a POST operation, you can set the encoding in the HTML <form> tag. For example, this form tag sets SJIS as the character set for the content:

  <form action="http://some.host.com/myWebApp/foo/index.html">
    <input type="application/x-www-form-urlencoded; charset=SJIS">
  </form>
  

  When the form is read by WebLogic Server, it processes the data using the SJIS character set.

• Because all Web clients do not transmit the information after the semicolon in the above example, you can set the codeset to be used for requests by using the <input-charset> element in the WebLogic-specific deployment descriptor, weblogic.xml. The <java-charset-name> element defines the encoding used to convert data when the URL of the request contains the path specified with the <resource-path> element.

  For example:

  <input-charset>
    <resource-path>/foo/*</resource-path>
    <java-charset-name>SJIS</java-charset-name>
  </input-charset>
  

  This method works for both GET and POST operations.

  For more information on the Web Application deployment descriptor, see Writing the WebLogic-Specific Deployment Descriptor (weblogic.xml).

 

---

Mapping IANA Character Sets to Java Character Sets

The names assigned by the Internet Assigned Numbers Authority (IANA) to describe character sets are sometimes different than the names used by Java. Because all HTTP communication uses the IANA character set names and these names are not always the same, WebLogic Server internally maps IANA character set names to Java character set names and can usually determine the correct mapping. However, you can resolve any ambiguities by explicitly mapping an IANA character set to the name of a Java character set.

To map a IANA character set to a Java character set the character set names in the <charset-mapping> element of the WebLogic-specific deployment descriptor, weblogic.xml. Define the IANA character set name in the <iana-charset-name> element and the Java character set name in the <java-charset-name> element. For example:

<charset-mapping>
    <iana-charset-name>Shift-JIS</iana-charset-name>
    <java-charset-name>SJIS</java-charset-name>
</charset-mapping>