You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Jon Stevens <jo...@latchkey.com> on 2001/08/21 03:31:15 UTC
Re: cvs commit: jakarta-tomcat-service/docs service.css
service.html
Why is this a .html file and not a .xml file?
-jon
on 8/20/01 6:13 PM, "pier@apache.org" <pi...@apache.org> wrote:
> 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:pier.fumagalli@sun.com"><pier.fumagalli@sun.com></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>
>
>
Re: cvs commit: jakarta-tomcat-service/docs service.css
service.html
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Jon Stevens at jon@latchkey.com wrote:
> Why is this a .html file and not a .xml file?
Because the service code is not built using Java, 99.9% of it is C code, and
I don't need ANT to build it... I don't want to rely on something "JAVA" to
build the docs... It's plain unformatted HTML... All styling is done in the
CSS... Being the spec, I prefer to have it plain (either HTML or plaintext),
functional documentation, we'll see...
Pier