1
Introduction

The Oracle Servlet Engine (OSE) works as a specialized Web server, designed as a scalable servlet server inside the Oracle8i database.

The servlet classes are loaded into Oracle8i with a loadjava command and published in a namespace inside the database. A servlet runner handles HTTP requests, instantiates published servlets in sessions, and invokes servlet methods.

The following sections contains descriptions and diagrams of the following topics:

• Serving Web Applications

• Web Services

• Summary of Containment Hierarchy

• Security

You can use one of the create commands to define domains, contexts, and servlets. All contents are served by servlets. The servlet location is defined by the client in the URL.

Serving Web Applications

A Web page is defined as an HTML file containing only static HTML descriptions of hyperlinks, and graphic and formatted text display. A Web application provides users with a more interactive experience than a static page can deliver. When HTML content is extended by servlets, creating dynamic content, that Web page becomes a Web application.

Session Memory and Scalability

The OSE is designed for virtually unlimited linear scalability. because each browser session is matched with a single virtual Java virtual machine (JVM), there can be multiple virtual JVMs (see Figure 1-1, "Browser Sessions Matched With Virtual JVMs"). The only limit on database platforms supporting the virtual JVM sessions is the amount of hardware present at any given time. See the Oracle8iJava Developers Guide for detailed information.

Figure 1-1 Browser Sessions Matched With Virtual JVMs

Although OSE serves static pages and runs CGI scripts, it is intended to be deployed as a servlet runner behind a standard Web server, such as Apache, Netscape, or IIS. See Chapter 5, "Apache Module for Oracle OSE".

One of the differences between OSE and other servlet engines is how the database session used is designed. Browser-sessions set up servlets sessions. The database session contains all the HTTP session objects created for that particular browser session. By employing database session memory, objects are not dropped after the request (connection) ends. However, objects are dropped when the database session ends.

OSE in the Database

OSE is a built-in Web server running inside Oracle8i supporting Web applications. Each session (virtual Java VM) executes the following items:

• JavaServer Pages (JSP)

• Servlets

• JavaStored Procedures

Database Sessions

The sessions terminate either explicitly or on a time-out configured by the administrator. For more information, see Chapter 6, "OSE Server Configuration".

The OSE unique attributes are:

• All servlets are activated in a browser-session sponsored database session.

• Each database session has its own virtual JVM. There are multiple virtual JVMs--one for every browser session.

• The OSE uses one virtual JVM per session, isolating the sessions and their static variables from each browser session (rather than creating a new thread with every browser session).

• The database session contains all the HTTP session objects created for that particular browser session.

• An HTTPsession is activated per stateful servlet context upon the servlet's request.

• An Oracle module, mod_ose, provides a layer between the Oracle HTTP server (Apache) and the Oracle8i database holding the Oracle servlet server (OSE). mod_ose defines ports, servers, and web domains by setting communication variables.

Web Services

In the hierarchical arrangement of this environment, OSE serves as an execution context for one or more Web services. You must specify a service root in the namespace when you create a Web service. The service root is the top level that contains the domain information for the entire Web service.

When you configure a Web service in OSE, you create a Web service, its end points, Web domains, and servlet contexts. A Web service is associated with one or more network end points. HTTP clients, who connect to a Web service end point, get contents from one of the associated Web domains. You must also configure all the attributes so that information in the namespace configuration has paths and pointers defined to handle and execute the requests.

OSE supports two types of Web service configurations:

• single-domain

• multi-domain

A single-domain Web service is sufficient for most cases. Configure the Web service to listen on a single port (8080 is used in all of our examples) and send any request received at the end point to the unique domain.

To support HTTPS, associate an additional end point to the single-domain Web service. This end point listens to a different port (9090 is used in all our examples), and you can configure it for SSL connections.

The multi-domain Web service is used for more advanced configurations, such as:

• In the virtual hosts configuration, one server with multiple Internet domain name system (DNS) names corresponds to multiple Web domains.

• In the multiple IP address configuration, one server with multiple network interface cards (NICs) corresponds to multiple Web domains.

In the multi-domain scenario, the network uses either the IP addressing, or the host name, or both to establish the request connection and to route the request to the correct domain.

Web Domains

A Web domain contains servlet contexts or, in the case of IP and virtual hosted, multi-domained Web services, another Web domain.

The Web domain for HTTP requests is identified by the address part of the URL. The root of the Web domain is located in the service root of the contining Web service.

Note: You can change the configuration of your Web domain structure from the default with tools that are described in the Oracle Java Tools Reference.

The configuration parameters of each domain are in the config object in the Web domain's directory tree. Graphical representations of these configurations are shown in Figure 1-2, "Single Domain Namespace Model Structure" and Figure 1-3, "Multi-Domain, Multi-Homed Example with Virtual Hosts In the Structure". Notice the config object at the top level of the structure.

The following list describes the Web domain hierarchy:

• A Web domain has an owner corresponding to the schema namespace directory owner.

• For the single-domain case, service root is the location for both the Web domain and the root of the Web service. (See Figure 1-2, "Single Domain Namespace Model Structure".)

• For the IP host domain case, the Web domain name is the host name located in the service root. (See Figure 1-3.)

• For the virtual host domain case, the Web domain name is the virtual host name, located in the service root. (See Figure 1-3.)

• A /contexts subdirectory, located in the domain root, contains the servlet contexts directories.

• The published servlets are under the /named_servlets directory.

• Parallel to the /named_servlets directory are configuration parameters in the namespace objects, config, httpSecurity, policy, defaultservlet, and doc_root.

• The doc_root object is a pointer (soft link) to static contents on the client.

The directory structure describing the namespace is a model you can use to explore and manipulate the elements that make up the Web domain. Each file and directory are actually objects with properties in the Oracle8i databases, rather than files with contents. However, for most of this discussion, a directory and file model will suffice while using the tools to create a Web domain.

Single-Domain

When a URL, such as http://cavist.com:8080/cellar/welcome.html, is sent to a single-domain, the request accesses the Web service listening on port 8080, on the host named cavist.com.

Example 1-1 Single-Domain: Port Relationship and Domain Root in URL

Figure 1-2 Single Domain Namespace Model Structure

Multi-Domain

When you set-up a multi-domain Web service, the Web domain name is dependent on the configuration type of the service root. An example of a multi-domain, multi-homed configuration (more than one IP address on a machine) combined with multiple virtual hosts is shown in Figure 1-3.

For example, a virtual host, cavist.com, in a domain defined by the IP address, 10.1.1.20, can have the identical structure naming pattern as another IP address and virtual host pairing, such as 10.1.1.30 hosting jones.com, sharing the same service root. The names are defined in a path so that the lower branches are uniquely defined by the domain names.

Example 1-2 Multiple-Domain: Port Relationship and service root in URL

Figure 1-3 Multi-Domain, Multi-Homed Example with Virtual Hosts In the Structure

Servlet Contexts

Think of a servlet context as an application loaded into OSE. It is a set of servlets, configuration parameters, JSPs, and pointers to static contents on the file system that are all accessible below the same virtual path. The servlet context is usually identifiable as the first segment of a URL's path.

A servlet context configuration describes how the Web server behaves when serving its contents (security, timeouts, MIME types, mapping of virtual paths extensions to servlets, statefulness). OSE supports nested servlet contexts that can inherit configuration properties from their parents.

In practice:

• The servlet context parent directory, /contexts, is a namespace subdirectory of its domain root directory.

• The winecellar servlet context is stored in the <domain root>/contexts/winecellar directory.

• The servlet context directory contains its configuration parameters, a pointer to the static document root, and a subdirectory, named_servlets, containing servlets.

The configuration information of a servlet context is a namespace object, config, in the servlet context directory. Look at Figure 1-2, "Single Domain Namespace Model Structure" and notice the config object listed under the <servlet context1> directory.

If the config object contains the entry /cellar as mapped to /winecellar, then the URL http://cavist.com:8080/cellar/welcome.html would access the servlet context, winecellar, in the Web domain, cavist.com.

Example 1-3 Mapping Virtual Paths to Servlet Contexts

Servlets

A servlet is a Java class. Load servlet classes and any related support classes, into the database with the loadjava command. Publish the servlet into a servlet context with the session shell.

Publishing a servlet:

• creates a named namespace object in the named_servlets subdirectory of the servlet context directory

• associates a virtual path with the servlet, as contained in the config object of their servlet context to be used when matching against a URI

Example 1-4 Servlets Associated with the HTTP Virtual Path

A servlet accessible as http://cavist.com:8080/cellar/winefinder could be published as a namespace object named
service root/contexts/winecellar/named_servlets/winefinderservlet with the virtual path mapping entry /winefinder=winefinderservlet in service root/contexts/winecellar/config.

Java Naming and Directory Interface

Earlier, we said the servlets are published in a namespace and that the directory structure was a model. This namespace is the Sun Java Naming and Directory Interface (JNDI). The OSE's JNDI implementation uses SQL tables to store the contents of a JNDI accessible namespace.

Access the JNDI with the session shell command-line tool. Use these commands to explore and manipulate the namespace.

Using the session shell you can navigate the namespace as if it were a file system to change directories and list the contents (see Chapter 3, "JNDI and the Session Shell" for tool definitions and examples).

The contents are organized into hierarchical containment relationships of security, mapping, servlets and default objects. Servlet contexts correspond to applications deployed in the Web server. Servlet contexts, which are mapped to the address part of an URL, are grouped in Web domains.

Example 1-5 URL Shows a Client Accessing Contents

http://<Web domain:port>/<servlet-context>/<path>

We can translate this example URL into a real URL and name such as this:

http://cavist.com:8080/winecellar/welcome.html

Web domains and servlet contexts have owners (Oracle schema) with full administration rights. The owner of the Web domain can administer the Web domain, create servlet contexts, and give access to other schemas. The owner of a servlet context can publish contents in it and tune its configuration parameters.

Permission and Schema

The ownership and permissions are similar in construct to the UNIX environment, in that there are read, write, and execute abilities defined with session shell commands. Web domain schemas are the only valid users in the JNDI namespace. The users are given permissions and ownership in their domains by administrators.

Summary of Containment Hierarchy

The containment hierarchy of the OSE is defined as:

Web Service(s) > Web Domain(s) > Servlet Context(s) > Servlets

Security

OSE supports authentication and access control as required by the Servlet 2.2 Specification.

In defining your security, you must define a valid set of users. You can:

• use the database users as its population

• define your own realm principals

Principal declarations are held in the realms directory of a Web service. The following are properties of realms:

• Realm definitions are within the scope of a service.

• A realm is made up of users and groups.

• All servlet contexts within a service can use the same realm definitions.

The policy directory is automatically created when you set permissions and create URL security mappings.

See Figure 1-4, "Security Components in the JNDI Namespace", for the general relationship of policy to a servlet context.

Figure 1-4 shows the relationship of the realms and policy directories with respect to the rest of the domain in the JNDI namespace. realms is at the top level of the domain, whereas policy is a sub-directory of servlet context.

Figure 1-4 Security Components in the JNDI Namespace

Versions

OSE supports servlets 2.1 and JSPs 1.0.

---