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

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`

Start the session shell tool.
Create a new servlet context.

Enter:

$createcontext

-virtualpath

/cellar

/webdomains

winecellar

virtualPath

domainName

servlet context

List the context.

Enter:

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

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

Start the session shell.
$ cd /webdomains/contexts/winecellar

$ 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:

Write the servlet code.
Compile the servlet.
Load the servlet class in the database.
Publish the servlet.
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:

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

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

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

7Developer Tools and Procedures