Author: sebb Date: Fri Jan 8 00:55:10 2010 New Revision: 897069 URL: http://svn.apache.org/viewvc?rev=897069&view=rev Log: DAEMON-60 Improve documentation
Modified: commons/proper/daemon/trunk/README commons/proper/daemon/trunk/xdocs/binaries.xml commons/proper/daemon/trunk/xdocs/index.xml commons/proper/daemon/trunk/xdocs/jsvc.xml commons/proper/daemon/trunk/xdocs/procrun.xml Modified: commons/proper/daemon/trunk/README URL: http://svn.apache.org/viewvc/commons/proper/daemon/trunk/README?rev=897069&r1=897068&r2=897069&view=diff ============================================================================== --- commons/proper/daemon/trunk/README (original) +++ commons/proper/daemon/trunk/README Fri Jan 8 00:55:10 2010 @@ -15,12 +15,12 @@ 2 - procrun: procrun is only for windows cd src/native/nt/procrun; make - (It is also possible to use the m$ developement tools). + (It is also possible to use the MS development tools). To build the documentation: (See http://jakarta.apache.org/commons/building.html). maven site:generate (Do not forget to get ../commons-build: (cd ..; svn co http://svn.apache.org/repos/asf/jakarta/commons/proper/commons-build/trunk/ commons-build)) -To deploy the documentation to apache site: +To deploy the documentation to the apache site: maven -Dmaven.username=${user.name} site:deploy (Check <siteAddress/> in project.xml). Modified: commons/proper/daemon/trunk/xdocs/binaries.xml URL: http://svn.apache.org/viewvc/commons/proper/daemon/trunk/xdocs/binaries.xml?rev=897069&r1=897068&r2=897069&view=diff ============================================================================== --- commons/proper/daemon/trunk/xdocs/binaries.xml (original) +++ commons/proper/daemon/trunk/xdocs/binaries.xml Fri Jan 8 00:55:10 2010 @@ -28,24 +28,24 @@ <p> In the directory <a href="http://www.apache.org/dist/commons/daemon/binaries/">binaries</a> -you find subdirectories containing executables +you will find subdirectories containing executables corresponding to your operating system. If your machine is not in the list, -please mail us and we will try to make it available or try to build it on your own. +please mail us and we will try to make it available, or you can try to build it on your own. The files are compressed tar files. They are named <code>jvm_name-os_name</code>. For example: In the directory <code>freebsd</code> we have <code>jdk1.4.1-FreeBSD_4.9.tar.gz</code> That is a file built on FreeBSD 4.9 using the FreeBSD JVM 1.4.1. </p> </section> -<section name="How do I get the excutable?"> +<section name="How do I get the executable?"> <subsection name="jsvc"> <p> -You have to do the following: +Do the following: <ul> - <li>Find the nearest tar file corresponding to our configuration.</li> + <li>Find the tar file corresponding to your configuration.</li> <li>Download it.</li> - <li>Uncompress the tar file and extract it (better with a gnu tar).</li> - <li>Copy the executable in the location where you want to run it.</li> + <li>Uncompress the tar file and extract it (better with gnu tar).</li> + <li>Copy the executable to the location where you want to run it.</li> <li>Write an rc shell (see in <code>src/samples</code> and <code>src/native/unix/native/Tomcat.sh</code>) to get your java application started as a daemon. @@ -55,8 +55,8 @@ </subsection> <subsection name="procrun"> <p> -The <code>procrun.exe</code> has to be installed as a service. -See <a href="procrun.html">procrun</a> for more information. +The <code>procrun.exe</code> has to be installed as a service +(see <a href="procrun.html">procrun</a> for more information). </p> </subsection> </section> Modified: commons/proper/daemon/trunk/xdocs/index.xml URL: http://svn.apache.org/viewvc/commons/proper/daemon/trunk/xdocs/index.xml?rev=897069&r1=897068&r2=897069&view=diff ============================================================================== --- commons/proper/daemon/trunk/xdocs/index.xml (original) +++ commons/proper/daemon/trunk/xdocs/index.xml Fri Jan 8 00:55:10 2010 @@ -27,8 +27,8 @@ <section name="Introduction"> <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 + valid tool to develop reliable and performant server applications as + opposed to just applets and client applications. The major disadvantage of the Java platform is that still today the only portable way to start a Java application relies on a single point of entry: the <CODE><EM CLASS="key">public static void</EM> @@ -56,19 +56,25 @@ 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 + to terminate the Virtual Machine process. This method however, has + several disadvantages and risks: + <ul> + <li> + In case of a system-wide shutdown, the Virtual Machine process may be + shut down directly by the operating system without notifying the running + server application. + </li> + <li> + If an attacker finds out the shutdown message to send to the server + and discovers a way to send this message, he can easily interrupt + the server's operation, bypassing all the security restrictions implemented in the operating system. + </li> + </ul> </p> <p> Most multi-user operating systems already have a way in which server - applications are started and stopped, under Unix based operating systems + 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> @@ -91,16 +97,16 @@ <section name="Platforms"> <p> - Actually win32 and the UNIX like platforms are supported. - For win32 platfroms use <a href="procrun.html">procrun</a>. + Both win32 and UNIX like platforms are supported. + For win32 platforms use <a href="procrun.html">procrun</a>. For UNIX like platforms use <a href="jsvc.html">jsvc</a>. </p> </section> <section name="Initial Source of the Package"> -<p>The original Java classes come from the Jakarta Tomcat 4.0 project.</p> +<p>The original Java classes came from the Jakarta Tomcat 4.0 project.</p> -<p>The proposed package name for the Daemon component is +<p>The package name for the Daemon component is <code>org.apache.commons.daemon</code>. </p> </section> Modified: commons/proper/daemon/trunk/xdocs/jsvc.xml URL: http://svn.apache.org/viewvc/commons/proper/daemon/trunk/xdocs/jsvc.xml?rev=897069&r1=897068&r2=897069&view=diff ============================================================================== --- commons/proper/daemon/trunk/xdocs/jsvc.xml (original) +++ commons/proper/daemon/trunk/xdocs/jsvc.xml Fri Jan 8 00:55:10 2010 @@ -26,15 +26,19 @@ <body> <section name="Introduction"> <p> - Actually only the UNIX like platforms are supported. - The sources are located in the <code>src/native/unix</code> subdirectory of the - project sources. - For win32 platforms the cygwin emulation layer is used. See - <a href="http://www.cygwin.com/">cygwin</a> for more information. + Jsvc is a set of libraries and applications for making Java + applications run on UNIX more easily. It can run on win32 via + the cygwin emulation layer (see + <a href="http://www.cygwin.com/"> cygwin</a> for more information), + however win32 users may prefer to use <a href="procrun.html"> procrun</a> + instead. </p> <p> - In the future <a href="http://apr.apache.org/">APR</a> may be used - to provide more convenient platform support. + The sources are located in the src/native/unix subdirectory. +</p> +<p> + In the future <a href="http://apr.apache.org/"> APR </a> may be used + to provide more portable platform support. </p> </section> @@ -87,7 +91,7 @@ ./configure </source> -If your operating system is supported, configure will go thru cleanly, +If your operating system is supported, configure will go through cleanly, otherwise it will report an error (please send us the details of your OS/JDK, or a patch against the sources). To build the binaries and libraries simply do: @@ -143,6 +147,8 @@ set a Java system property -X<option> set Virtual Machine specific option + -procname <process name> + Allows the process name to be configured on Linux -wait <waittime> wait waittime seconds for the service to start waittime should multiple of 10 (min=10) @@ -156,16 +162,16 @@ <section name="Using jsvc"> <p> There two ways to use jsvc: via a Class that implements the Daemon interface or -via calling a Class that have the required methods. +via calling a Class that has the required methods. For example Tomcat-4.1.x uses the Daemon interface -and Tomcat-5.0.x provide a Class whose methods are called by jsvc directly. +whereas Tomcat-5.0.x provides a Class whose methods are called by jsvc directly. </p> <subsection name="Via Daemon interface"> <p> -You have to do the following. +Do the following: <ul> <li>Write a Class that implements the Daemon interface (MyClass).</li> - <li>Put it in the jarfile (my.jar).</li> + <li>Put it in a jarfile (my.jar).</li> <li>Call jsvc like: <source> ./jsvc -cp commons-daemon.jar:my.jar MyClass @@ -176,12 +182,12 @@ </subsection> <subsection name="Directly"> <p> -You have to write a Class (MyClass) that implements the following methods: +Write a Class (MyClass) that implements the following methods: <ul> - <li><code>void load(String[] arguments)</code>: Here open the configuration files, create the trace file, create - the ServerSockets, the Threads</li> - <li><code>void start()</code>: Start the Thread, accept incoming connections</li> - <li><code>void stop()</code>: Inform the Thread to live the run(), close the ServerSockets</li> + <li>void init(String[] arguments): Here open configuration files, create a trace file, create + ServerSockets, Threads</li> + <li>void start(): Start the Thread, accept incoming connections</li> + <li>void stop(): Inform the Thread to terminate the run(), close the ServerSockets</li> <li><code>void destroy()</code>: Destroy any object created in init()</li> </ul> Store it in a jarfile and use as above: Modified: commons/proper/daemon/trunk/xdocs/procrun.xml URL: http://svn.apache.org/viewvc/commons/proper/daemon/trunk/xdocs/procrun.xml?rev=897069&r1=897068&r2=897069&view=diff ============================================================================== --- commons/proper/daemon/trunk/xdocs/procrun.xml (original) +++ commons/proper/daemon/trunk/xdocs/procrun.xml Fri Jan 8 00:55:10 2010 @@ -26,7 +26,7 @@ <section name="Introduction"> <p> Procrun is a set of libraries and applications for making Java - applications to run on WIN32 much easier. + applications run on WIN32 more easily. </p> <subsection name="Procrun service application"> <p>