Oracle8i Oracle Servlet Engine User's Guide Release 3 (8.1.7) A83720-01 |
Library | Service | Contents | Index

# 7
Developer Tools and Procedures

This chapter uses examples and discussion to describe the OSE developer techniques and tools. The following topics are in this chapter:

- Web Services

- Managing Servlet Contexts

- What Is in a Servlet Context?

- Managing Published Servlets

- Writing a Servlet

## Web Services

A Web service contains one or more domains, depending on the configuration of the service. A newly created Web domain contains one servlet context, `default`. It serves contents for all requests that do not map to another servlet context. You can create specific servlets and servlet contexts for your own applications (see Figure 7-1, "JNDI default Servlet Context in the JNDI Namespace").

JNDI namespace directory structure in parallel to another servlet context. The same structure requirements apply to both branches of the JNDI namespace tree. See Figure 1-2 and Figure 1-3 for visual examples of single and multiple domains.

#### Figure 7-1 JNDI `default` Servlet Context in the JNDI Namespace

Use the `createwebservice` command to define properties of the service. The Oracle Java Tools Reference has a detailed description of this command.

### Virtual Host and IP Domains in the Web Service

In a single domain case, you do have neither an IP or a virtual host domain. The domain root is the service root. If you have a service configured to be a multi-domain service, as either a virtual host or an IP address, the domain will be rooted in the service root. If the service has both types of domains, IP address and a virtual host, the IP address is rooted in the service root, and the virtual host is contained in the IP address domain (see Figure 1-3, "Multi-Domain, Multi-Homed Example with Virtual Hosts In the Structure").

These domains are created by the `createwebdomain` command. See the Oracle Java Tools Reference for syntax and argument details.

### Changing Ports of the Web Service

Ports are associated with the corresponding presentation either statically or by using the dynamic registration commands. To support HTTPS, associate an additional SSL endpoint to the Web service.

Use the `addendpoint` command to configure the ports that are to be associated with the service (see Oracle Java Tools Reference for syntax and arguments).

## Managing Servlet Contexts

This section describes how to create, change, and delete a servlet context.

### Creating or Change a Servlet Context

Create new servlet contexts with the session shell `createcontext` command.

- You must have your username set with "write permission" in the containing domain's `contexts` directory to create a servlet context.

- You must have your username set with "write permission" in the containing domain's `config` object.

- The argument passed in as the virtual path gets entered into the domain's `config` object, making the new servlet context accessible to HTTP clients.

- Servlets execute using the identity of the creator of the context.

`createcontext` defines and sets up some or all the following properties:

- defines the virtual path associated with this context

- initializes context with a list of properties

- (optional) defines the location of the static pages

- (optional) destroys and replaces previously existing named context

- (optional) if flagged stateless, the context is stateless-- servlets are not allowed to obtain the HTTPSession object

In Example 7-1, "Creating a Servlet Context Named, winecellar", the servlet context handles all HTTP requests beginning with, `http://<``host-name``>:8080/cellar`

#### Example 7-1 Creating a Servlet Context Named, `winecellar`

1. Start the session shell tool.

2. Create a new servlet context.

   Enter:

   `$``createcontext` | `-virtualpath` | `/cellar` | `/webdomains` | `winecellar`
   |  | virtualPath | domainName | servlet context

3. List the context.

   Enter:

       $ ls /webdomains/contexts
       ./            ../           default/      winecellar/

4. The context is also listed in the Web service virtual path mappings. Enter:

   `$` `getgroup /webdomains/config contexts`

       /cellar=winecellar

### Deleting a Servlet Context

Remove a servlet context and all servlets in the context with the session shell tool `destroycontext` command. The mapping in the domain `config` object is removed as well.

## What Is in a Servlet Context?

A servlet context encapsulates the notion of a web application. A servlet context contains several entries that represent its configuration and contents. You can see the entries with the session shell tool.

#### Example 7-2 Servlet Context Entries of `winecellar` Representing Configuration and Content

1. Start the session shell.

2. `$` `cd /webdomains/contexts/winecellar`

3. `$` `ls`

       ./
       ../
       config
       doc_root
       named_servlets/
       defaultservlet
       policy
       httpSecurity

### config Object

The `config` entry has a set of properties controlling the behavior of the servlet context. You can see and modify the `config` object with the session shell commands that manage object properties. See Oracle Java Tools Reference for more information.

### doc_root Object

The `doc_root` object is a JNDI object representing an instance of class `SYS:oracle.aurora.namespace.filesystem.FSContextImpl` that serves as a link to the file system. The `doc_root` object is where the static content is located. It has one property known as `FSContextURL`. The file system path of the static contents of the servlet context, is stored in the `FSContextURL` property.

### named_servlets Subdirectory

The `named_servlets` subdirectory contains the servlets published in the servlet context. Each published servlet is a JNDI object representing an instance of class `SYS:oracle.aurora.mts.ServletActivation`.

### defaultservlet Object

If there is an entry in the servlet context named, `defaultServlet`, that servlet is used when no other servlet matches the request. If there is no entry in the servlet context for a default servlet, one is provided by the containing service.

### policy Directory

The `policy` directory contains security configuration entries. See details in Chapter 8, "Security HTTP Administration".

### httpSecurity

The security servlet, `httpSecurity`, functions as the first filter for all requests. This servlet handles security by raising an exception or not raising an exception and allowing the request processing to proceed. See details in Chapter 8, "Security HTTP Administration".

### Servlet Context Group Parameters

This section contains the full list of groups and properties that a servlet context `config` object supports.

The group, `context.properties`, lists a set of properties that control the servlet context.

#### Example 7-3 Viewing and Modifying config Properties

    $ getproperties config
    --group--=context.properties
    context.browse.dirs=true
    context.welcome.names=index.html
    context.accept.charset=ISO-8859-1
    context.accept.language=en
    context.default.languages=*
    context.default.charsets=*
    --group--=context.params
    ...
    --group--=context.mime
    java=text/plain
    html=text/html
    ...

    $ addgroupentry config context.properties context.browse.dirs false
    $ getgroup config context.properties
    context.browse.dirs=false
    context.welcome.names=index.html
    context.accept.charset=ISO-8859-1
    context.accept.language=en
    context.default.languages=*
    context.default.charsets=*

#### context.params

The `context.params` group is a list of arbitrary name/value pairs that are accessible at runtime by the servlet context `getAttribute` method.

#### Example 7-4 Servlet Context getAttribute Method

If you have the following parameters:

    $ getgroup config context.properties
    details=high

You can access the details parameter in a servlet as follows:

    public void doGet (HttpServletRequest request, HttpServletResponse response)
        ...  {
        ...
        String details = getServletContext().getAttribute ("details");
        if (details.equals ("high")) {
          ...
        }

#### context.mime

The group `context.mime` lists the MIME types that the servlet context supports. This group has the same format as the MIME types group in the Web domain configuration.

#### context.servlets

When you publish servlets, you associate them with virtual paths, and you can see these virtual paths with the session shell `getgroup` command. See the section, "JNDI default Servlet Context in the JNDI Namespace" for more information.

The group `context.servlets` lists the virtual path mapping for the published servlets. It contains a list of name/value pairs, where the name part is the virtual path, and the value part is the name of a servlet to handle the virtual path. The servlet name is relative to the `named_servlets` directory of the servlet context. The name portion of the pair contains either a virtual path or a wild-card name.

#### context.error.uris

The group `context.error.uris` associates HTTP error codes with URIs within the servlet context that are used to report errors to the HTTP clients. Often, these URIs are handled by the default servlet and are relative to the `doc_root` parameter of the servlet context.

    $ getgroup config context.error.uris

    401=/system/errors/401.html
    403=/system/errors/403.html
    404=/system/errors/404.html
    406=/system/errors/406.html
    500=/errors/internal

## Managing Published Servlets

A servlet is published once it has a servlet activation entry in the `named_servlets` directory and the virtual path that is mapped in the servlet context `config` object.

This section discusses how to manage the servlets published in the OSE.

### Servlet Classes Published in a Servlet Context

The session shell `publishservlet` and `unpublishservlet` commands modify the `named_servlets` directory and the servlet context config object. The servlets are created (published) or removed with their associated paths and names.

Published servlets are JNDI objects of class `SYS:oracle.aurora.mts.ServletActivation`. To be accessible from an HTTP client, servlets must be associated with a virtual path or a star-name, in their servlet context.

#### Example 7-5 Publishing a Servlet

    $ publishservlet -virtualpath /tastings \
           /webdomains/contexts/winecellar tastingServlet \
            SCOTT:winemasters.tasting.Tasting

Note: The backslash is a line continuation aide. It is a shell tool command line convention to assist with very long entries.

#### Example 7-6 Verifying the New Servlet and Virtual Path Mappings

    # Verify the servlet is here
    $ getproperties /webdomains/contexts/winecellar/named_servlets/tastingServlet
      servlet.class=SCOTT:winemasters.tasting.Tasting

        # Verify the virtual path mapping
    $ getgroup /webdomains/contexts/winecellar/config context.servlets
    /errors/internal=internalError
    /tastings=tastingServlet

A newly published servlet has only one property, the`servlet.class`. The `servlet.class` specifies the full name of the servlet class: the schema and the fully qualified path within the schema. If no schema is specified, the current schema is used.

You can add additional properties with session shell commands and access additional properties from the servlet code with the `getInitParameter()` method call.

#### Example 7-7 Adding Properties to the Servlet

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

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

You can access the servlet properties with the following code:

    public void doGet (HttpServletRequest request, HttpServletResponse response)
       {
    ...
       String details = getServletConfig().getInitParameter ("details");
     if (details.equals ("high")) {
    ...
       }

## Writing a Servlet

Once you have configured OSE, you can begin writing and deploying servlets and JSPs.

Note: A prerequisite for this section is understanding the "Endpoints" section in chapter "Architecture". A good reference book on servlets, such as the "Java Servlet Programming" (O'Reilly and Associates), is needed to cover the basics of building servlets.

We support the Servlet 2.2 specification.

The following steps describe the method of writing and publishing a servlet:

1. Write the servlet code.

2. Compile the servlet.

3. Load the servlet class in the database.

4. Publish the servlet.

5. Open the servlet from a Web browser.

### Writing the Servlet Code

A servlet book will give a full spectrum of examples and tutorials. Please see a servlet book for assistance in writing the code.

### Compiling the Servlet

To compile the servlet, you must have the following jar(s) in your CLASSPATH:

1. The jar containing the http classes: `$(ORACLE_HOME)/jis/lib/servlet.jar`

2. If your servlet accesses the database, you also must have the JDBC classes:

       - %(ORACLE_HOME)/jdbc/lib/classes12.zip
       - % javac -classpath .:$(ORACLE_HOME)/jis/lib/servlet.jar HelloWorld.java

### Loading the Servlet Code

Load the servlet with the `loadjava` command. See the documentation on `loadjava` in the "JServer Concepts Manual".

    % loadjava -u scott/tiger -r HelloWorld.class

### Publishing the Servlet

Here we publish in the default context. We are mapping the servlet to the virtualpath /hello.

    $ publishservlet -virtualpath /hello /webdomains/contexts/default helloServlet SCOTT:HelloWorld

If you change the servlet, you must reload it in the database, but it is not necessary to republish the servlet in the Web server.

### Accessing the Servlet

You can now see the servlet in a Web browser, using the URL:
`http://<host>:8080/hello`

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index