Engine User's Guide
Release 3 (8.1.7)
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:
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.
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.
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.
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 is a built-in Web server running inside Oracle8i supporting Web applications. Each session (virtual Java VM) executes the following items:
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:
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:
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 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.
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.
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:
/contextssubdirectory, located in the domain root, contains the servlet contexts directories.
named_servletsdirectory are configuration parameters in the namespace objects,
doc_rootobject 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.
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
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.
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.
/contexts, is a namespace subdirectory of its domain root directory.
winecellarservlet context is stored in the <domain root>
named_servlets, containing servlets.
The configuration information of a servlet context is a namespace object,
config, in the
context directory. Look at Figure 1-2, "Single Domain Namespace Model Structure" and notice the
config object listed under 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,
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:
named_servletssubdirectory of the servlet context directory
configobject of their servlet context to be used when matching against a URI
A servlet accessible as
http://cavist.com:8080/cellar/winefinder could be published as a namespace object named
/contexts/winecellar/named_servlets/winefinderservlet with the virtual path mapping entry
/winefinder=winefinderservlet in service root
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.
We can translate this example URL into a real URL and name such as this:
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.
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.
The containment hierarchy of the OSE is defined as:
Web Service(s) > Web Domain(s) > Servlet Context(s) > Servlets
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:
Principal declarations are held in the
realms directory of a Web service. The following are properties of realms:
contextswithin a service can use the same realm definitions.
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
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.
OSE supports servlets 2.1 and JSPs 1.0.