pier 01/08/20 18:13:13
Added: docs service.css service.html
Log:
Initial (not finished yet) writing of a specification for Service classes.
Revision Changes Path
1.1 jakarta-tomcat-service/docs/service.css
Index: service.css
===================================================================
BODY {
font-family: arial, helvetica, sans-serif;
font-size: 10pt;
text-align: justify;
}
H1 {
border-width: 2px;
border-style: ridge;
border-color: #cccccc;
background-color: #ddddff;
font-size: 14pt;
font-weight: bold;
text-align: center;
padding: 2px;
}
H2 {
border-width: 2px;
border-style: ridge;
border-color: #cccccc;
background-color: #eeeeff;
font-size: 12pt;
font-weight: bold;
text-align: left;
padding: 2px;
}
H3 {
font-size: 10pt;
font-weight: bold;
text-align: left;
}
H4 {
font-size: 8pt;
font-weight: normal;
font-style: italic;
text-align: center;
}
P {
margin-left: 20px;
}
P.note {
border-width: 1px;
border-style: ridge;
border-color: #cccccc;
background-color: #ffffee;
font-size: 8pt;
font-weight: normal;
text-align: justify;
margin-left: 20%;
margin-right: 20%;
padding: 4px;
}
P.copyright {
font-size: 8pt;
font-weight: normal;
text-align: center;
}
PRE {
border-width: 1px;
border-style: ridge;
border-color: #cccccc;
background-color: #eeeeee;
font-size: 8pt;
font-weight: normal;
text-align: left;
margin-left: 10%;
margin-right: 10%;
padding: 4px;
}
CODE {
font-size: 8pt;
white-space: pre;
font-weight: normal;
}
EM.key {
color: #000099;
font-style: normal;
white-space: pre;
}
EM.ref {
color: #990000;
font-style: normal;
white-space: pre
}
EM.com {
color: #009900;
font-style: normal;
white-space: pre
}
OL {
list-style: decimal outside;
font-size: 10pt;
}
OL OL {
list-style: lower-alpha outside;
font-size: 8pt;
}
A:link {
color: #0000ee;
text-decoration: none;
white-space: pre;
}
A:visited {
color: #0000ee;
text-decoration: none;
white-space: pre;
}
A:active {
color: #0000ee;
text-decoration: none;
white-space: pre;
}
1.1 jakarta-tomcat-service/docs/service.html
Index: service.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Apache Service Specification - Version 1.0</TITLE>
<LINK REL="stylesheet" TYPE="text/css" HREF="service.css" TITLE="service">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=ISO-8859-1">
</HEAD>
<BODY>
<H1>Apache Service Specification</H1>
<H4>Version 1.0</H4>
<P CLASS="note">
<strong>Abstract:</strong>
This document specifies the behavior and life cycle of an abstract
Java™ service, in relation to its native container. In addition
it defines a mechanism for controlling a service, and its interaction
with the native OS process in which its existance is confined.
</P>
<H2>Index</H2>
<OL>
<LI><A HREF="#1">Introduction</A>
<LI><A HREF="#2">Scope of this specification</A>
<LI><A HREF="#3">The Service interface and its life cycle</A>
<OL>
<LI><A HREF="#3A">Instantiation</A>
<LI><A HREF="#3B">Initialization</A>
<LI><A HREF="#3C">Startup</A>
<LI><A HREF="#3D">Stop</A>
<LI><A HREF="#3E">Destruction</A>
</OL>
</OL>
<A NAME="1"><H2>Introduction</H2></A>
<P>
Since 1994, the Java™ programming language evolved and became a
valid tool to develop, other than applets and client applications,
reliable and performant server applications. The major disadvantage of
the Java™ platform is that still today the only portable way to
start a Java™ applcation relies on a single point of entry: the
<CODE><EM CLASS="key">public static void</EM> main(<EM
CLASS="ref">String</EM>[])</CODE>
method.
</P>
<P>
Having a single-point of entry is a valid solution for client
applications, where interactively a user can command to the application
to quit (which can terminate the Virtual Machine process at calling the
<CODE><EM CLASS="ref">System</EM>.exit(<EM CLASS="key">int</EM>)</CODE>
method), but in those cases where the application is not interactive
(server applications) there is currently no portable way to notify
the Virtual Machine of its imminent shutdown.
</P>
<P>
A server application written in Java might have to perform several tasks
before being able to shutdown the Virtual Machine process. For example
in the case of a Servlet container, before the VM process is shut down,
sessions might need to be serialized to disk, and web applications need
to be destroyed.
</P>
<P>
One common solution to this problem is to create (for example) a
<CODE><EM CLASS="ref">ServerSocket</EM></CODE> and wait for a particular
message to be issued. When the message is received, all operations
required to shut down the server applications are performed and at the
end the <CODE><EM CLASS="ref">System</EM>.exit</CODE> method is called
to terminate the Virtual Machine process. This method, however, implies
several disadvantages and risks: for example in case of a system-wide
shutdown, it might happen that the Virtual Machine process will be shut
down directly by the operating system, without notifying the running
server application. Or, for example, if an attacker finds out what is
the required message to send to the server, and discovers a way to send
this message to the running server application, he can easily interrupt
the operation of a server, bypassing all the security restrictions
implemented in the operating system.
</P>
<P>
Most multi-user operating systems already have a way in which server
applications are started and stopped, under Unix based operating systems
non interactive server applications are called <em>daemons</em> and are
controlled by the operating system with a set of specified
<em>signals</em>. Under Windows such programs are called <em>services</em>
and are controlled by appropriate calls to specific functions defined in
the application binary, but although the ways of dealing with the problem
are different, in both cases the operating system can notify a server
application of its imminent shutdown, and the application has the
ability to perform certain tasks before its process of execution is
destroyed.
</P>
<A NAME="2"><H2>Scope of this specification</H2></A>
<P>
The scope of this specification is to define an API in line with the
current Java™ Platform APIs to support an alternative invocation
mechanism which could be used instead of the above mentioned
<CODE><EM CLASS="key">public static void</EM> main(<EM
CLASS="ref">String</EM>[])</CODE>
method. This specification cover the behavior and life cycle of what
we define as "Java ™ services", or, in other words,
non interactive Java™ applications.
</P>
<P>
This specification does not cover how the container of a Java™
service must be implemented, or how to build a native liaison between
the operating system and the <CODE><EM CLASS="ref">Service</EM></CODE>
interface, but defines the relation between the an operating system
process and the <CODE><EM CLASS="ref">Service</EM></CODE> implementation
life cycle. It should be trivial for implementors to build a native
liaison and container for Java™ services.
</P>
<P>
This specification, together with the related API documentation, can be
used by software deveopers to build portable non interactive applications
based on the Java™ platform.
</P>
<A NAME="3"><H2>The Service interface and its life cycle</H2></A>
<P>
The <CODE><EM CLASS="ref">Service</EM></CODE> interface (defined as
follows) is the main interface representing a Java™ service:
</P>
<PRE>
<EM CLASS="key">package</EM> org.apache.service;
<EM CLASS="key">public interface</EM> <EM CLASS="ref">Service</EM>
<EM CLASS="key">extends</EM> <EM CLASS="ref">Runnable</EM> {
<EM CLASS="key">public void</EM> init(<EM CLASS="ref">ServiceContext</EM>
context)
throws <EM CLASS="ref">Exception</EM>;
<EM CLASS="key">public void</EM> run();
<EM CLASS="key">public void</EM> die();
<EM CLASS="key">public void</EM> destroy();
}</PRE>
<P>
A service is managed through a well defined life cycle that defines how
it is loaded, initialized, started, stopped and destroyed. This life
cycle is expressed in the API by the <CODE>init(...)</CODE>,
<CODE>run()</CODE>, <CODE>die()</CODE> and <CODE>destroy()</CODE> methods
of the <CODE><EM CLASS="ref">Service</EM></CODE> interface.
</P>
<A NAME="3A"><H3>Instantiation</H3></A>
<P>
The service container is responsible for instantiating services. Because
of this, concrete implementations of the <CODE><EM
CLASS="ref">Service</EM></CODE>
interface must always expose a public void constructor, which will be
used by the service container to create instances of the class.
For example:
</P>
<PRE>
<EM CLASS="key">package</EM> mypackage;
<EM CLASS="key">import</EM> org.apache.service.*;
<EM CLASS="key">public class</EM> <EM CLASS="ref">MyService</EM>
<EM CLASS="key">implements</EM> <EM CLASS="ref">Service</EM> {
<EM CLASS="com">/** This constructor must be here. */</EM>
<EM CLASS="key">public</EM> MyService() {
super();
...
}
...
}</PRE>
<P>
Once the Virtual Machine process is started in the underlying operating
system, and the Virtual Machine itself is created and configured, the
service container associated with its native liaison constructs a new
instance of the concrete class implementing the
<CODE><EM CLASS="ref">Service</EM></CODE> instance. It is not defined by
this specification how the instance is constructed, or how many instances
of one or more concrete services implementation can coexist in the same
Virtual Machine.
</P>
<P>
As a side note, in case of multiple services running within the scope
of the same virtual machine, developers should not rely on static
methods and variables for proper operation, as it is advisable for
security reasons to load each different service instance in a separate
class loader.
</P>
<A NAME="3B"><H3>Initialization</H3></A>
<P>
After the service instance has been constructed, the container must
initialize it before it can be started. Initialization is provided so
that a service can read persisten configuration data, access native
resources, and perform other one-time activities.
</P>
<P>
Under certain operating systems (typically Unix based operating systems),
and if the native liaison of the container supports and it is configured
accordingly, this method might be called with super-user privileges.
For example, within the scope of this method, it might be wise to create
all required <CODE><EM CLASS="ref">ServerSocket</EM></CODE> instances (as
under several operating systems this requires super-user privileges).
</P>
<P>
That said, it is very important that within the scope of this method
"untrusted" data cannot be processed (for example, starting
an acceptor thread on a <CODE><EM CLASS="ref">ServerSocket</EM></CODE>
which receives and processes data from unknown sources), as this would
serious security hazards.
</P>
<P>
The service container must guarantee that the <CODE>init(...)</CODE>
method is called at least once, and only once on an instance of a
service object, and that it will be called before any access to the
<CODE>run()</CODE>, <CODE>die()</CODE> or <CODE>destroy()</CODE>
methods.
</P>
<P>
During initialization, the service instance can throw any
<CODE><EM CLASS="ref">Exception</EM></CODE> preventing a the successful
completion of the <CODE>init(...)</CODE> method. In this case the service
instance must not be started, and the <CODE>destroy()</CODE> method must
not be called before the instance is released by the container to allow
garbage collecting.
</P>
<A NAME="3C"><H3>Startup</H3></A>
<P>
As the <CODE><EM CLASS="ref">Service</EM></CODE> interface extends the
<CODE><EM CLASS="ref">Runnable</EM></CODE> interface, to start the
operation of a service, the container calls the <CODE>run()</CODE> method
within the scope of a <CODE><EM CLASS="ref">Thread</EM></CODE>. A
service is said to be "running" until the thread
</P>
<HR>
<P CLASS="copyright">
Author Pier Fumagalli
<A HREF="mailto:[EMAIL PROTECTED]";><[EMAIL PROTECTED]></A>
<BR>
Copyright © 2001, The Apache Software Foundation
<A HREF="http://www.apache.org/";><http://www.apache.org/></A>
<BR>
All rights reserved.
</P>
<P CLASS="copyright">
Sun, Sun Microsystems, Solaris, and Java are trademarks or registered
trademarks of Sun Microsystems, Inc.
<A HREF="http://www.sun.com/";><http://www.sun.com/></A>
<BR>
UNIX® is a registered trademark in the United States and other
countries, exclusively licensed through X/Open Company, Ltd.
<A HREF="http://www.opengroup.org/";><http://www.opengroup.org/></A>
<BR>
Windows, WinNT and Win32 are registered trademark of Microsoft Corp.
<A HREF="http://www.microsoft.com/";><http://www.microsoft.com/></A>
</P>
</P>
</BODY>
</HTML>
