Engine User's Guide
Release 3 (8.1.7)
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:
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.
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.
There are session shell commands for use with the namespace. There are different styles of commands which are characterized as follows:
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.
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
The syntax for the
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., >
setproperties doc_root FSContextURL=/usr/local/winecellar
For more information on
doc_root, see "doc_root
Virtual paths can be associated with a servlet when publishing it to the servlet context sub-directory,
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.
Defines a group of parameters within a JNDI entry.
In the previous sections you read about, and perhaps tested, examples of JNDI objects with these procedures:
This section explains how to publish and run a servlet using the following commands:
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
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 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
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
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.
Verify the servlet is published, enter:
$ ls /webdomains/contexts/winecellar/named_servlets
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
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.
The Web domain that handles the requests is dependent on the Web service that is configured for OSE.
The Web domain handling the request is the single Web domain associated with the service.
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.
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.
If the URL is:
and the virtual path from the Web domain
config object maps the
virtual path to the servlet context:
Then the servlet context,
cavist/contexts/winecellar, is used.
If a servlet context match is not found, the request is served by the context:
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.
The virtual path
is served by the context
To find the name of the servlet,
bordeaux.wine is matched against the virtual paths mapping, defined by the servlet context
Within the servlet context, if a servlet match is not found, the request is served by the default servlet.
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.
winecellar/doc_root object points to the file system directory,
Therefore, the contents of the
doc_root object parameters are
The URL is
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:
This match must be full matches. If no default servlet is found, OSE generates an internal error code.