src/docs/daemon.html - commons-daemon - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
 <HTML>
   <HEAD>
     <TITLE>Apache Daemon Specification - Version 1.0</TITLE>
     <LINK REL="stylesheet" TYPE="text/css" HREF="daemon.css" TITLE="daemon">
     <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=ISO-8859-1">
   </HEAD>
   <BODY>

     <H1>Apache Daemon 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&trade; daemon, in relation to its native container. In addition
       it defines a mechanism for controlling a daemon, 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 Daemon 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&trade; 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&trade; platform is that still today the only portable way to
       start a Java&trade; 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>daemons</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&trade; 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 &quot;Java &trade; daemons&quot;, or, in other words,
       non interactive Java&trade; applications.
     </P>
     <P>
       This specification does not cover how the container of a Java&trade;
       daemon must be implemented, or how to build a native liaison between
       the operating system and the <CODE><EM CLASS="ref">Daemon</EM></CODE>
       interface, but defines the relation between the an operating system
       process and the <CODE><EM CLASS="ref">Daemon</EM></CODE> implementation
       life cycle. It should be trivial for implementors to build a native
       liaison and container for Java&trade; daemons.
     </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&trade; platform.
     </P>

     <A NAME="3"><H2>The Daemon interface and its life cycle</H2></A>
     <P>
       The <CODE><EM CLASS="ref">Daemon</EM></CODE> interface (defined as
       follows) is the main interface representing a Java&trade; daemon:
     </P>
 <PRE>
 <EM CLASS="key">package</EM> org.apache.commons.daemon;

 <EM CLASS="key">public interface</EM> <EM CLASS="ref">Daemon</EM>
 <EM CLASS="key">extends</EM> <EM CLASS="ref">Runnable</EM> {

     <EM CLASS="key">public void</EM> init(<EM CLASS="ref">DaemonContext</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 daemon 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">Daemon</EM></CODE> interface.
     </P>

     <A NAME="3A"><H3>Instantiation</H3></A>
     <P>
       The daemon container is responsible for instantiating daemons. Because
       of this, concrete implementations of the <CODE><EM CLASS="ref">Daemon</EM></CODE>
       interface must always expose a public void constructor, which will be
       used by the daemon container to create instances of the class.
       For example:
     </P>

 <PRE>
 <EM CLASS="key">package</EM> mypackage;

 <EM CLASS="key">import</EM> org.apache.commons.daemon.*;


 <EM CLASS="key">public class</EM> <EM CLASS="ref">MyDaemon</EM>
 <EM CLASS="key">implements</EM> <EM CLASS="ref">Daemon</EM> {

     <EM CLASS="com">/** This constructor must be here. */</EM>
     <EM CLASS="key">public</EM> MyDaemon() {
         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
       daemon container associated with its native liaison constructs a new
       instance of the concrete class implementing the
       <CODE><EM CLASS="ref">Daemon</EM></CODE> instance. It is not defined by
       this specification how the instance is constructed, or how many instances
       of one or more concrete daemons implementation can coexist in the same
       Virtual Machine.
     </P>
     <P>
       As a side note, in case of multiple daemons 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 daemon instance in a separate
       class loader.
     </P>

     <A NAME="3B"><H3>Initialization</H3></A>
     <P>
       After the daemon instance has been constructed, the container must
       initialize it before it can be started. Initialization is provided so
       that a daemon 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
       &quot;untrusted&quot; 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 daemon container must guarantee that the <CODE>init(...)</CODE>
       method is called at least once, and only once on an instance of a
       daemon 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 daemon 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 daemon
       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">Daemon</EM></CODE> interface extends the
       <CODE><EM CLASS="ref">Runnable</EM></CODE> interface, to start the
       operation of a daemon, the container calls the <CODE>run()</CODE> method
       within the scope of a <CODE><EM CLASS="ref">Thread</EM></CODE>. A
       daemon is said to be &quot;running&quot; until the thread
     </P>


     <HR>
     <P CLASS="copyright">
       Author Pier Fumagalli
       <A HREF="mailto:pier.fumagalli@sun.com">&lt;pier.fumagalli@sun.com&gt;</A>
       <BR>
       Copyright &copy; 2001, The Apache Software Foundation
       <A HREF="http://www.apache.org/">&lt;http://www.apache.org/&gt;</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/">&lt;http://www.sun.com/&gt;</A>
       <BR>
       UNIX&reg; is a registered trademark in the United States and other
       countries, exclusively licensed through X/Open Company, Ltd.
       <A HREF="http://www.opengroup.org/">&lt;http://www.opengroup.org/&gt;</A>
       <BR>
       Windows, WinNT and Win32 are registered trademark of Microsoft Corp.
       <A HREF="http://www.microsoft.com/">&lt;http://www.microsoft.com/&gt;</A>
     </P>
     </P>
   </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<HTML>
	<HEAD>
	<TITLE>Apache Daemon Specification - Version 1.0</TITLE>
	<LINK REL="stylesheet" TYPE="text/css" HREF="daemon.css" TITLE="daemon">
	<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=ISO-8859-1">
	</HEAD>
	<BODY>

	<H1>Apache Daemon 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™ daemon, in relation to its native container. In addition
	it defines a mechanism for controlling a daemon, 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 Daemon 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>daemons</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 ™ daemons", or, in other words,
	non interactive Java™ applications.
	</P>
	<P>
	This specification does not cover how the container of a Java™
	daemon must be implemented, or how to build a native liaison between
	the operating system and the <CODE><EM CLASS="ref">Daemon</EM></CODE>
	interface, but defines the relation between the an operating system
	process and the <CODE><EM CLASS="ref">Daemon</EM></CODE> implementation
	life cycle. It should be trivial for implementors to build a native
	liaison and container for Java™ daemons.
	</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 Daemon interface and its life cycle</H2></A>
	<P>
	The <CODE><EM CLASS="ref">Daemon</EM></CODE> interface (defined as
	follows) is the main interface representing a Java™ daemon:
	</P>
	<PRE>
	<EM CLASS="key">package</EM> org.apache.commons.daemon;

	<EM CLASS="key">public interface</EM> <EM CLASS="ref">Daemon</EM>
	<EM CLASS="key">extends</EM> <EM CLASS="ref">Runnable</EM> {

	<EM CLASS="key">public void</EM> init(<EM CLASS="ref">DaemonContext</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 daemon 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">Daemon</EM></CODE> interface.
	</P>

	<A NAME="3A"><H3>Instantiation</H3></A>
	<P>
	The daemon container is responsible for instantiating daemons. Because
	of this, concrete implementations of the <CODE><EM CLASS="ref">Daemon</EM></CODE>
	interface must always expose a public void constructor, which will be
	used by the daemon container to create instances of the class.
	For example:
	</P>

	<PRE>
	<EM CLASS="key">package</EM> mypackage;

	<EM CLASS="key">import</EM> org.apache.commons.daemon.*;


	<EM CLASS="key">public class</EM> <EM CLASS="ref">MyDaemon</EM>
	<EM CLASS="key">implements</EM> <EM CLASS="ref">Daemon</EM> {

	<EM CLASS="com">/** This constructor must be here. */</EM>
	<EM CLASS="key">public</EM> MyDaemon() {
	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
	daemon container associated with its native liaison constructs a new
	instance of the concrete class implementing the
	<CODE><EM CLASS="ref">Daemon</EM></CODE> instance. It is not defined by
	this specification how the instance is constructed, or how many instances
	of one or more concrete daemons implementation can coexist in the same
	Virtual Machine.
	</P>
	<P>
	As a side note, in case of multiple daemons 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 daemon instance in a separate
	class loader.
	</P>

	<A NAME="3B"><H3>Initialization</H3></A>
	<P>
	After the daemon instance has been constructed, the container must
	initialize it before it can be started. Initialization is provided so
	that a daemon 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 daemon container must guarantee that the <CODE>init(...)</CODE>
	method is called at least once, and only once on an instance of a
	daemon 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 daemon 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 daemon
	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">Daemon</EM></CODE> interface extends the
	<CODE><EM CLASS="ref">Runnable</EM></CODE> interface, to start the
	operation of a daemon, the container calls the <CODE>run()</CODE> method
	within the scope of a <CODE><EM CLASS="ref">Thread</EM></CODE>. A
	daemon 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>