Configuring Web Application Components

Configuring Web Application Components

Contents

Configuring Servlets
Configuring Java Server Pages
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 Resources in a Web Application
Determining the Encoding of an HTTP Request
Mapping IANA Character Sets to Java Character Sets

Configuring Servlets

You define servlets as a part of a Web application in several entries in web.xml. 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.) This element also contains definitions for initialization attributes and security roles for the servlet. The second entry, under the <servlet-mapping> element, defines the URL pattern that calls this servlet.

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 showing the URLs used to invoke these servlets.
<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>
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 kiwiIf 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

ServletServlet can be used to create a default mappings for servlets. For example, to create a default mapping to map all servlets to /myservlet/*, so the servlets can be called using...
http://host:port/web-app-name/myservlet/com/foo/FooServlet

...add the following to your web.xml file:
<servlet>
    <servlet-name>ServletServlet</servlet-name>
    <servlet-class>weblogic.servlet.ServletServlet</servlet-class>
</servlet>

<servlet-mapping> 
  <servlet-name>ServletServlet</servlet-name>
    <url-pattern>weblogic.servlet.ServletServlet</url-pattern>
</servlet-mapping>
Servlet Initialization Attributes

You define initialization attributes for servlets in web.xml, using the <init-param> element of the <servlet> element, using <param-name> and <param-value> tags. For example:
<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>
Configuring Java Server Pages

To deploy JSP files place them under the root directory of a Web application. You define JSP configuration attributes in the <jsp-descriptor> element of weblogic.xml. These attributes 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

Registering a JSP as a Servlet

You can register a JSP as a servlet using the <servlet> element. A servlet container maintains a map of the servlets known to it. This map is used to resolve requests that are made to the container. Adding entries into this map is known as "registering" a servlet. You add entries to this map by referencing a <servlet> element in web.xml through the <servlet-mapping> entry.
A JSP is a type of servlet; registering a JSP is a special case of registering a servlet. Normally, JSPs are implicitly registered the first time you invoke them, based on the name of the JSP file. Therefore, the myJSPfile.jsp file would be registered as myJSPfile.jsp in the mapping table. You can implicitly register JSPs, as illustrated in the following example. In this example, you request the JSP with the name /main instead of the implicit name myJSPfile.jsp.
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 as a servlet allows you to specify the load order, initialization attributes, and security roles for a JSP, just as you would for a servlet.

Configuring JSP Tag Libraries

Weblogic Server lets you create and use custom JSP tags. Custom JSP tags are Java classes you can call 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. You make this TLD available to the Web application containing the JSP by defining it in web.xml. 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.xml, 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 web.xml:
<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.
WebLogic Server also includes several custom JSP tags that you can use in your applications. These tags perform caching, facilitate query attribute-based flow control, and facilitate iterations over sets of objects.

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, you edit the Web application deployment descriptor, web.xml. 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:

index.html
index.htm
index.jsp

The following is an example Welcome page configuration:
<servlet>
 <servlet-name>WelcomeServlet</servlet-name>
 <servlet-class>foo.bar.WelcomeServlet</servlet-class>
</servlet>

<servlet-mapping>
 <servlet-name>WelcomeServlet</servlet-name>
 <url-pattern>*.foo</url-pattern>
</servlet-mapping>

<welcome-file-list>
 <welcome-file>/welcome.foo</welcome-file>
</welcome-file-list>
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.
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:

Define your servlet as described in Configuring Servlets
If you still want the FileServlet to serve files with other extensions:

Define a servlet and give it a <servlet-name>, for example myFileServlet.
Define the <servlet-class> as weblogic.servlet.FileServlet.
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.

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

Using CGI with WebLogic Server

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

Configuring WebLogic Server to Use CGI

To configure CGI in WebLogic Server:
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.
Register the following initialization attributes 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). If you do not specify cgiDir, the directory defaults to a directory named cgi-bin under the Web application root.
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 attribute 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.
<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 attribute.

CGI Best Practices

The following are CGI best practices with respect to calling a subscript:
You can use sh subscript.sh for both exploded (unarchived) Web applications and archived Web applications (WAR files).
You can use sh $PWD/subscript.sh for both exploded (unarchived) Web applications and archived Web applications (WAR files).
You can use sh $DOCUMENT_ROOT/$PATH/subscript.sh for exploded (unarchived) Web applications. You cannot use it, however, for archived Web applications (WAR files). This is due to the fact that the document root might point you to the root of your WAR file, and the scripting language cannot open that WAR file and locate the subscript.sh needed for execution. This is true not only for sh, but for any scripting language.

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 ClasspathServlet is always enabled by default. To disable it, set the ServerMBean parameter ClassPathServletDisabled to true (default = false).
The ClasspathServlet returns the classes or resources from the system CLASSPATH in the following order:

WEB-INF/classes
jar files under WEB-INF/lib/*
system CLASSPATH

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/myWebApp/classes/my/resource/myClass.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
Note that because 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 Resources in a Web Application

The resources that you use in a Web application are generally deployed externally to the application. JDBC DataSources can optionally be deployed within the scope of the Web application as part of an EAR file.
Prior to WebLogic Server 7.0, JDBC DataSources were always deployed externally to the Web application. To use external resources in the Web application, you resolve the JNDI resource name that the application uses with the global JNDI resource name using the web.xml and weblogic.xml deployment descriptors.
WebLogic Server versions 7.x and later enable you to deploy JDBC DataSources as part of the Web application EAR file by configuring those resources in the weblogic-application.xml deployment descriptor. Resources deployed as part of the EAR file are referred to as application-scoped resources. These resources remain private to the Web application, and application components can access the resource names directly from the local JNDI tree at java:comp/env.

Configuring External Resources

When accessing external resources (resources not deployed with the application EAR file) such as a DataSource from a Web application via Java Naming and Directory Interface (JNDI), you can map the JNDI name you look up in your code to the actual JNDI name as bound in the global 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:

Enter the resource name in the deployment descriptor as you use it in your code, the Java type, and the security authorization type.
Map the resource name to the JNDI name.

The following example illustrates how to use an external DataSource. It assumes that you have defined a data source called accountDataSource.
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 External EJBs

Web applications can access EJBs that are deployed as part of a different application (a different EAR file) by using an external reference. The EJB being referenced exports a name to the global JNDI tree in its weblogic-ejb-jar.xml deployment descriptor. An EJB reference in the Web application module can be linked to this global JNDI name by adding an <ejb-reference-description> element to its weblogic.xml 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.
To reference an external EJB for use in a Web application:

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 web.xml.
Map the reference name in the <ejb-reference-description> element of in weblogic.xml to the JNDI name defined in the weblogic-ejb-jar.xml file.
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.

More about the ejb-ref* Elements

The ejb-ref element in the web.xml deployment descriptor declares that either a servlet or JSP is going to be using a particular EJB. The ejb-reference-description element in the weblogic.xml deployment descriptor binds that reference to an EJB, which is advertised in the global JNDI tree.
The ejb-reference-descriptor element indicates which ejb-ref element it is resolving with the ejb-ref-name element. That is, the ejb-reference-descriptor and ejb-ref elements with the same ejb-ref-name element go together.
With the addition of the ejb-link syntax, the ejb-reference-descriptor element is no longer required if the EJB being used is in the same application as the servlet or JSP that is using the EJB.
The ejb-ref-name element serves two purposes in the web.xml deployment descriptor:
It is the name that the user code (servlet or JSP) uses to look up the EJB. Therefore, if your ejb-ref-name element is ejb1, you would perform a JNDI name lookup for ejb1 relative to java:comp/env. The ejb-ref-name element is bound into the component environment (java:comp/env) of the Web application containing the servlet or JSP.
Assuming the ejb-ref-name element is ejb1, the code in your servlet or JSP should look like:
Context ctx = new InitialContext(); 
ctx = (Context)ctx.lookup("java:comp/env"); 
Object o = ctx.lookup("ejb1"); 
Ejb1Home home = (Ejb1Home) PortableRemoteObject.narrow(o, Ejb1Home.class);
It links the ejb-ref and ejb-reference-descriptor elements together.
Referencing Application-Scoped EJBs

Within an application, WebLogic Server binds any EJBs referenced by other application components to the environments associated with those referencing components. These resources are accessed at runtime through a JNDI name lookup relative to java:comp/env.
The following is an example of an application deployment descriptor (application.xml) for an application containing an EJB and a Web application, also called an Enterprise Application. (For the sake of brevity, the XML header is not included in this example.)
<application>
     <display-name>MyApp</display-name>
     <module>
        <web>
           <web-uri>myapp.war</web-uri>
           <context-root>myapp</context-root>
        </web>
     </module>
     <module>
        <ejb>ejb1.jar</ejb>
     </module>
  </application>
To allow the code in the Web application to use an EJB in ejb1.jar, the Web application deployment descriptor (web.xml) must include an <ejb-ref> stanza that contains an <ejb-link> referencing the JAR file and the name of the EJB that is being called.
The format of the <ejb-link> entry must be as follows:
filename#ejbname 
...where filename is the name of the JAR file, relative to the Web application, and ejbname is the EJB within that JAR file. The <ejb-link> element should look like the following:
 
<ejb-link>../ejb1.jar#myejb</ejb-link>
Note that since the JAR path is relative to the WAR file, it begins with "../". Also, if the ejbname is unique across the application, the JAR path may be dropped. As a result, your entry may look like the following:
<ejb-link>myejb</ejb-link>
The <ejb-link> element is a sub-element of an <ejb-ref> element contained in the Web application's web.xml descriptor. The <ejb-ref> element should look like the following:
<web-app>
  ...
  <ejb-ref>
     <ejb-ref-name>ejb1</ejb-ref-name>
     <ejb-ref-type>Session</ejb-ref-type>
     <home>mypackage.ejb1.MyHome</home>
     <remote>mypackage.ejb1.MyRemote</remote>
     <ejb-link>../ejb1.jar#myejb</ejb-link>
  </ejb-ref>
  ...
</web-app>
Referring to the syntax for the <ejb-link> element in the above example,
<ejb-link>../ejb1.jar#ejb1</ejb-link>,
the portion of the syntax to the left of the # is a relative path to the EJB module being referenced. The syntax to the right of # is the particular EJB being referenced in that module. In the above example, the EJB JAR and WAR files are at the same level.
The name referenced in the <ejb-link> (in this example, myejb) corresponds to the <ejb-name> element of the referenced EJB's descriptor. As a result, the deployment descriptor (ejb-jar.xml) of the EJB module that this <ejb-ref> is referencing should have an entry an entry similar to the following:
<ejb-jar>
  ...
  <enterprise-beans>
     <session>
        <ejb-name>myejb</ejb-name>
        <home>mypackage.ejb1.MyHome</home>
        <remote>mypackage.ejb1.MyRemote</remote>
        <ejb-class>mypackage.ejb1.MyBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
     </session>
  </enterprise-beans>
  ...
</ejb-jar>
Notice the <ejb-name> element is set to myejb.
At runtime, the Web application code looks up the EJB's JNDI name relative to java:/comp/env. The following is an example of the servlet code:
MyHome home = (MyHome)ctx.lookup("java:/comp/env/ejb1");
The name used in this example (ejb1) is the <ejb-ref-name> defined in the <ejb-ref> element of the web.xml segment above.

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 code set was used to encode the request.
There are two ways you can define the code set:
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 code set to be used for requests by using the <input-charset> element in 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.
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 from 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 on IANA character set to a Java character, set the character set names in the <charset-mapping> element in 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>

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