2
The Servlet Basics with OSE

This chapter contains a series of operations designed to be helpful during your first time using the servlet engine. The topics we cover are the following:

JNDI

The JNDI namespace is an API storing information and contents of the servers, and provides naming and directory functionality to applications written in the Java programming language. JNDI is independent of specific naming or directory service implementations, enabling Java applications to access different naming and directory services with a common API. Various naming and directory service providers are plugged in seamlessly behind the common API, which allows Java applications to coexist with legacy applications and systems, such as a file system.

A full JNDI server, inside Oracle8i, is accessible with JNDI APIs from inside and outside of Oracle8i. When managing the Web server, you can interactively see and change the contents and properties of the namespace with session shell tool. See the Oracle Java Tools Reference for a complete discussion of the session shell commands and syntax.

The namespace is hierarchical, with two types of entries, objects and directories.

Objects are used to store Java references.
Directories contain other directories or objects. Paths to JNDI entries are indicated with the regular UNIX notation /dir/dir/dir/leaf.

Figure 2-1 JNDI OSE Namespace Structure Showing dir/dir/dir/leaf

Session Shell

The session shell commands, shown in this section, are used in the most commonly performed tasks in the OSE management. In the following sections, you will see a simple set of commands used to create and manipulate objects in the JNDI.

Note:
If a multiple line entry is invoked by using a double-quote, the session shell prompts for the next entry with a right-angle bracket, ">", until another double-quote is entered.
Another method for multiple line entries is to use a backslash "\" as a continuation indicator.

There are session shell commands for use with the namespace. There are different styles of commands which are characterized as follows:

a UNIX-like command set for exploring and manipulating the namespace
commands to get and set properties of JNDI objects
specialized commands to create new objects (for example, the servlet contexts and their configuration parameters, and servlets).

See Chapter 3, "JNDI and the Session Shell" for an overview of these commands. Read Oracle Java Tools Reference for a complete description of these commands.

Getting and Setting Object Parameters

Use the getproperties command to show all parameters of a JNDI object and the setproperties command to change the parameters. You can also change the parameters, along with their entire group parameters, using the setgroup command.

The syntax for the setparameters and getparameters are:

getproperties <object>
setproperties <object> <properties>

In getproperties, the properties are printed as a Java properties file. In setproperties the properties need to be passed in with the same syntax. You will likely have more than one property. Enter a double-quote before the first property, and use the carriage return after each entry. The shell prompts with an angle bracket (>) for more data or an end of entry. Use double-quotes after entering the last property, marking the last entry (i.e., >foo=bar").

Note:
The setproperties command clears all of the properties of the object before setting the specified properties.

Example 2-1 Change the doc_root Path

$ getproperties doc_root
  FSContextURL=/usr/local/oracle/jis/public_html

$ setproperties doc_root FSContextURL=/usr/local/winecellar

$ getproperties doc_root
  FSContextURL=/usr/local/winecellar

Note:
When entering the new path, specify the whole path.

For more information on doc_root, see "doc_root Object", .

Virtual Paths

Virtual paths can be associated with a servlet when publishing it to the servlet context sub-directory, named_servlets.

Given that an URL is defined by:
protocol + servername + URI, then the structure is: http://<servername>/<URI>.

The URI, shown as part of the URL, is defined is the request URI comprised of the
ContextPath + ServletPath + PathInfo

The first portion of the virtual path mapping to a servlet context is called the servlet context's virtual path; the second portion mapping into a particular servlet is called the Servlet's virtual path. Any left over portion in the URI is given as PATH_INFO to the servlet.

Property Groups

Defines a group of parameters within a JNDI entry.

Deploy a Servlet

In the previous sections you read about, and perhaps tested, examples of JNDI objects with these procedures:

Create a JNDI object.
Display properties of the doc_root object, with the getproperties command.

This section explains how to publish and run a servlet using the following commands:

loadjava
publishservlet
setproperties

Servlet Classes Published in a Servlet Context

Servlet classes are loaded into Oracle8i with loadjava and published in a servlet context with the session shell commands. Publishing a Servlet creates a JNDI object in the named_servlets subdirectory of the servlet contexts.

This JNDI object lists the servlet classname and its initialization parameters. Servlets are associated with an HTTP virtual path as described in their JNDI servlet context config object.

Use loadjava to load the servlet class and any support classes into the database. (See Oracle Java Tools Reference for a detailed description of this tool.)

Published Servlets

Published servlets are JNDI objects of class SYS:oracle.aurora.mts.ServletActivation under the named_servlets directory of a servlet context. To be accessible from an HTTP client, servlets must be associated with a virtual path, or a wild-card name, in their servlet context config.

publishservlet [-virtualpath <path>] [-stateless] [-reuse] [-properties props] \

 contextName <servletName> [className]

-virtualpath option and path (optional): virtual path to associate with this servlet for invocation

-stateless flag (optional): tells OSE the servlet is stateless. When this is set, the servlet has no access to the HTTPSession.

contextName: the name assigned to this context servlet directory.

servletName: the name assigned to this servlet in the named_servlets directory.

className: the name of the class implementing the HttpServlet interface.

This command publishes a servlet by name in the context and associates a virtual path with the named servlet.

Example 2-2 Publish a Servlet with publishservlet Command

Verify the servlet is published, enter:

$ ls /webdomains/contexts/winecellar/named_servlets


  tastingServlet

Verify the virtual path mapping, enter:

$ getgroup /webdomains/contexts/winecellar/config context.servlets /errors/internal=internalError /tastings=tastingServlet

Example 2-3 Modify a Published Servlet Properties with setproperties Command

You can add additional properties with the session shell commands then access those new properties from the servlet code with the setproperties.

$ getproperties invoker
  servlet.class=SCOTT:winemasters.tasting.Tasting

$ setproperties invoker "servlet.class=SCOTT:winemasters.tasting.Tasting
  >details=high 
  >style=parker"


$ getproperties invoker
  servlet.class=SCOTT:winemasters.tasting.Tasting
  details=high
  style=parker

Serving an HTTP Request

This section describes the algorithm OSE uses to find the right servlet.

Servlets handle all HTTP requests. The request deployment begins when a client sends an HTTP request to the server. OSE extracts the virtual path from the request.

When a service is invoked, the config object uses the virtual path to map the servlet to the request.

The following four sections describe how HTTP requests are serviced.

Finding the Web Domain

The Web domain that handles the requests is dependent on the Web service that is configured for OSE.

Single-Domain Web Service:

The Web domain handling the request is the single Web domain associated with the service.

Multi-Domain Web Services:

If you configured more advanced Web Services, then the domain used depends on the service and the URL employed to access OSE. Refer to the Multi-Domain discussion in Chapter 1, "Introduction" for more information.

Finding the Servlet Context

OSE searches in the contexts properties group of the Web domain config object. This set of properties is a list of mappings for virtual paths to Context names.

OSE matches the virtual path of the request against each entry in the Contexts properties. The longest match indicates which servlet context will serve the request.

Example 2-4 HTTP Requests Finding the Servlet Context

If the URL is:

http://cavist.com:8080/cellar/bordeaux.wine

and the virtual path from the Web domain config object maps the
virtual path to the servlet context:

/cellar=/winecellar

Then the servlet context, cavist/contexts/winecellar, is used.

If a servlet context match is not found, the request is served by the context:

/cavist/contexts/default

Mapping the Virtual Path to a Servlet

When the servlet is mapped to the URI, the portion of the URI path that was mapped to the servlet context is ignored. The remaining portion is matched with entries in the context.servlets properties of the servlet context config object. The longest match indicates which servlet will handle the request.

Entries in the context.servlets properties can be paths or wild-card names according to the Servlet 2.2 Specification. Partial paths have priority over wild-card names. Exact matches have priority over both partial paths and wild-card names.

Example 2-5 HTTP Requests Finding the Servlet

The virtual path /cellar/bordeaux.wine
is served by the context /cavist/contexts/winecellar.

To find the name of the servlet, bordeaux.wine is matched against the virtual paths mapping, defined by the servlet context config object.

Within the servlet context, if a servlet match is not found, the request is served by the default servlet.

Trying the Default Servlet - Static Content

If no match for the requested URL is found, OSE looks for a servlet named defaultservlet, first in the servlet context directory, next in the Web domain directory, and then in the Web Service. If the default servlet is found, it processes the request.

Example 2-6 Request Served by defaultservlet

Suppose the winecellar/doc_root object points to the file system directory, /usr/local/coolplace/html

Therefore, the contents of the doc_root object parameters are
FSContextURL=/usr/local/coolplace/html

The URL is http://cavist.com:8080/cellar/labels/lafitte.gif

The virtual path, /cellar is mapped to a servlet context, /winecellar. If the servlet context did not have any matches for /labels/lafitte.gif (or a partial match, such as /labels/*), then the default servlet is used.

The default servlet:

starts and receives the pathInfo, /labels/lafitte.gif
matches the pathInfo below doc_root.
retrieves /usr/local/coolplace/html/labels/lafitte.gif

This match must be full matches. If no default servlet is found, OSE generates an internal error code.

2The Servlet Basics with OSE