Author: sgoeschl
Date: Tue Jan 1 14:55:53 2008
New Revision: 607940
URL: http://svn.apache.org/viewvc?rev=607940&view=rev
Log:
First cut of a tutorial before I accidently delete it
Added:
commons/sandbox/exec/trunk/src/site/apt/tutorial.apt
Added: commons/sandbox/exec/trunk/src/site/apt/tutorial.apt
URL:
http://svn.apache.org/viewvc/commons/sandbox/exec/trunk/src/site/apt/tutorial.apt?rev=607940&view=auto
==============================================================================
--- commons/sandbox/exec/trunk/src/site/apt/tutorial.apt (added)
+++ commons/sandbox/exec/trunk/src/site/apt/tutorial.apt Tue Jan 1 14:55:53
2008
@@ -0,0 +1,60 @@
+ --------
+Jakarta Commons Exec Tutorial
+ --------
+ --------
+14 December 2007
+ --------
+
+Jakarta Commons Exec
+
+* The First Encounter
+
+ At this point we can safely assume that you would like to start some stuff
from withing your
+ Java application and you spent some time here to do it properly. You look at
Commons Exec and think
+ "Wow - calling Runtime.exec() is a piece of cake and the Apache folks are
wasting their and my time
+ with tons of code".
+
+ Well, we learned it the hard way (in my case more than once) that using
plain Runtime.exec() can be
+ a painful experience. Therefore you are invited to delve into commons-exec
and having a look at the
+ hard lessons the easy way ...
+
+* Taming Your Process
+
+ Assume you are forced start Acrobat Reader 8.x from your Java server to
print a PDF document. The
+ very first question is - would you like to wait for the print process to
finish (synchronous
+ execution) or do you run it independent from your process (asnynchrounous
execution).q
+
+ You write
+ a tests, everything works but in production the server box crashes. A closer
look reveals that you
+ succeeded in starting the print process but it somehow never terminated. The
first lesson learned is
+ that you need to ensure that your print job terminates after a while - you
need a watchdog. Luckily
+ commons-exec provides such a thing
+
+ Reliably executing external processes can also require knowledge of the
environment variables before or after the
+ command is executed. In J2SE 1.1-1.4 there is not support for this, since
the method, <<<System.getenv()>>>, for
+ retriving environment variables is deprecated.
+
+ The are currently several different libraries that for their own purposes
has implemented frameworks around
+ <<<Runtime.exec()>>> to handle the various issue outlined above. The
proposed project should aim at coordinating and
+ learning from these initatives to create and maintain a simple, reusable and
well-tested package. Since some of the
+ more problematic platforms are not readily available, it is my hope that the
broad Apache community can be a
+ great help.
+
+* Scope of the package
+
+ The package shall create and maintain a process execution package written in
the Java language to be distributed
+ under the ASF license. The Java code might also be complemented with scripts
(e.g. Perl scripts) to fully enable
+ execution on some operating systems. The package should aim for supporting a
wide range of operating systems while
+ still having a consistent API for all platforms.
+
+* Identify the initial source for the package
+
+ Several implementations exists and should be researched before finalizing
the design:
+
+ * Ant 1.X contains probably the most mature code within the exec task. This
code has been stripped of the
+ Ant specifics and cleaned up by Niklas Gustavsson and can be donated under
the ASF license.
+
+ * Ideas from {{{http://ant.apache.org/ant2/actionlist.html#exec} Ant2}}
+
+ * plexus-utils has a similar but slimmer BSD-licensed implementation than Ant
that can be reused
+
