Date post: | 22-Feb-2015 |
Category: |
Documents |
Upload: | gottipati-sree-harsha |
View: | 1,314 times |
Download: | 7 times |
Welcome to YAJSW
Yet Another Java Service Wrapper
Welcome to YAJSW
Introduction1.
Project information2.
Changes3.
Comparison of wrapper frameworks4.
Requirements & Supported Platforms5.
Features6.
Quick Start
View Screencast1.
Installation of a java application using genConfig2.
7.
Migrating from JSW8.
Configuration9.
Configuration Generator 10.
Java Application Launching11.
Using YAJSW from within a java application
Starting a native image 1.
Starting a java application 2.
Reading the output stream of a wrapped application3.
Writing the input stream of a wrapped application4.
Restarting/Stopping the JVM from within a wrapped application5.
Getting a Thread Dump of the wrapped application6.
Installing a service7.
Starting a service8.
Stopping a service9.
Listening to state change10.
12.
Monitoring java applications
Monitoring Heap1.
Monitoring Memory2.
Monitoring Deadlocks3.
13.
Timers and Conditions14.
JMX Support15.
System Tray Support16.
Windows services17.
Unix/Linux Daemon18.
Mac OS X Daemon19.
Scripts
Shell Scripts1.
Groovy Scripts2.
Sample Scripts3.
Condition Scripts4.
Testing a script5.
20.
MSCS Cluster Aware Wrapper21.
Windows Session0 Isolation22.
OS Users23.
Entering passwords24.
YAJSW lib folder25.
Wrapper process java options26.
Wrapping groovy scripts27.
YAJSW groovified: WrapperBuilder28.
Building YAJSW29.
Network Launching of Applications - Experimental30.
Wrapping JNLP - Experimental31.
Java Web Start Support - Experimental - Currently only for windows32.
Services Manager - Experimental - Currently only for windows33.
Android Services Manager - experimental34.
Third party Libraries35.
1.
1.
Introduction
YAJSW is a java centric implementation of the java service wrapper by tanuki (JSW).
It aims at being mostly configuration compliant with the original. It should therefore be easy to switch from JSW to YAJSW.
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
1 of 21 8/4/2011 4:07 PM
JSW is a wonderful software I have been using for some time in production. So why yet another framework ?
The main reason is that I need a better integration within my java job scheduling framework (rzomx)
As of the next version the license of JSW will change making it impossible for me to use it in rzomx
I may need win64 support, which is currently not available or not free for JSW.
Project information
YAJSW project is managed on sourceforge
Please refer to the project page for licensing, user forums, bug tracking, file downloads.
Currently the project does not support mailing lists nor does it support a source code repository. The source is included in the download file.
Changes
Comparison of wrapper frameworks
YAJSW : Yet Another Java Service Wrapper
JSW : Java Service Wrapper
ACD : Apache Commons Daemon
L4J : Launch4j
Note: If you would like to add further frameworks or in case of errors in the table please inform me.
Features/Framework YAJSW JSW ACD
License LGPL GPL/Commercial Apache
Run as Windows Service X X X
Run as UNIX Daemon X X X
Support Mac OS X launchd X
Platform indepemdent installation of services/Daemons X
Java Embedable X
Wrap Java Application X X X
Wrap Groovy Script X
Wrap native executable X X
Wrap as executable
Portable Configuration X X
Capture and Log console output X X
Stop and Reconnect Wrapper X
Monitor Application X X X
Restart Application X X X
Single Instance Enforcement X X
Control Process Priority X X
Control Process Affinity X
Alert Emails X X (Commercial)
Scripting X
Timed Events and Event commands X X (Commercial)
Configuration generator X
Define Process Name X
Automatic selection of JVM X
JMX Support X X
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
2 of 21 8/4/2011 4:07 PM
System Tray + GUI Console X
Windows Cluster Aware X
Network launcher X
Support JNLP configuration X
Java Webstart launcher X
Requirements & Supported Platforms
YAJSW requires Java 1.5 or higher.
The current release is stable for win32 and win64
Tested on: Windows XP prof, Windows 2000 server, Windows 2003 32 & 64 bit server, Windows 2008 32 & 64 bit, Windows 7 32 & 64 bit,
Windows Vista
The current release is stable for Linux.
Tested on Suse 9, Suse 11.1 x86 and amd64, Ubuntu 9.04 32 & 64 bit, Ubuntu 10.4 32 & 64 bit
The current release is alpha for Mac OS X
Tested on 10.5.5
The current release is alpha for Solaris
Tested on Solaris 10 u6 x86
The current release is alpha for FreeBSD
Tested on FreeBSD 7.1 x86 and amd64
Goal of YAJSW is to support all platforms as JNA.
It should be easy to build it for other platforms supporting libffi
If you have tested it, or ported it on other platforms please notify me.
NOTE Windows vista, 7, etc: the batch files have to be run as administrator.
Features
Wrap any native executable, java process or groovy script and run it as windows service or linux daemon
Easy Platform Independent installation of services/daemons
Platform independent configuration
Support for platform specific configuration
Wild card for classpath directories and files
Capture console output, log it, trigger scripts or restart process on output matching regular expressions
Monitor and automatically restart hanging or crashed proceses
Trigger process execution and termination at specific cycles, times or scriptable conditions
Embed the wrapper within java applications
Read from process output or write to process input
Support for RunAs / sudo
Support for System Tray Icon. Display tray messages from a groovy script, for example in case of exceptions. Monitoring Console.
Support for generation of configuration file
Windows Cluster aware
Support for remote network launching
Support for jnlp configuration
License: LGPL
Quick Start
View Screencast
Installation of a java application using genConfig
Note: In the sequel script file names end with ".bat". For Linux please use the corresponding files which end with ".sh"
download YAJSW
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
3 of 21 8/4/2011 4:07 PM
Unpack the zip file to a folder <yajsw>.
Do not remove or copy files from this folder to any another folder. Do not rename any folders within <yajsw>. For this you may have
to change the manifest in the jar files.
Call java -version and make sure that your default java installation is 1.5 or higher
If this is not the case make sure that java 1.5 or higher is installed and adapt the environment variable java_exe in bat/setenv.bat or
setenv.sh. NOTE: to display system tray java 1.6 is required. For thread dump with locks java 1.6 is required.
Start the application you would like to wrap. For example start Tomcat. Check the process id of your application. NOTE: we need the
pid of the application not the batch file which started the application. You may use bat/runHelloWorld.bat, which starts a java
application which prints some numbers on the console.
Goto yajsw/bat and execute
genConfig.bat <pid>
NOTE: on posix systems (Linux) this command requires root priviliges to access information on other processes
This generates the file yajsw/conf/wrapper.conf which is the configuration file for wrapping your application
Stop your application
Open conf/wrapper.conf with a text editor and set the password for wrapper.app.password or comment out
wrapper.app.account (#). Also check the value of wrapper.ntservice.name
NOTE: you may also create a configuration file with a text editor. Use the file conf/wrapper.conf.ini as starting point.
NOTE: Mac OS X, Solaris: wrapper.working.dir is currently not determined automatically. You may have to edit this property.
NOTE: configuration generation is currently implemented only for java applications. It will be implemented for native image and
groovy in a later release. For native images or groovy scripts you will have to create the wrapper.conf file with a text editor.
Execute your wrapped application as console application by calling
runConsole.bat
check that your application (for example tomcat) is running
To Install the application as service call
installService.bat
To start the service:
startService.bat
To stop the service:
stopService.bat
To uninstall the service:
uninstallService.bat
Migrating from JSW
YAJSW configuration and command line interface are very similar to those of JSW. YAJSW however follows a diffrent architecture and therefore
supports the JSW integration methods differntly. A migration guide for JSW users has therefore been implemented.
Configuration
Configuration is mostly identical to JSW.
Detailed description of the YAJSWconfiguration properties is found here.
Properties can be defined in:
- wrapper.bat command line attributes
- WrappedProcess.getLocalConfiguration().setProperty()
- java system properties (example -Dwrapper.config=conf\wrapper.conf, or System.setProperty("wrapper.config", "conf\wrapper.conf") )
- in wrapper.conf file
- as operating system environment variables (example for win32: set wrapper.java=c:\java\jdk1.5\bin\java.exe)
Properties are searched in this order. Thus setting wrapper.java configuration in system properties will override the OS environment.
NOTE: In case of cascading wrapper applications, there are cases where system properties of the wrapper should not be used by the wrapped
application, when starting sub processes. This can be avoided by calling WrappedProcess.setUseSystemProperties(false);
NOTE: Do not change the configuration or scripts while the wrapper or application or service or daemon is running. To change the
configuration first stop the wrapper and the application.
NOTE: Before changing service/daemon configuration properties: stop and uninstall the service or daemon.
Configuration Generator
Creating a wrapper configuration file can be quite a nuisance. The configuration generator helps you generate the configuration.
Given a process id (pid) the configuration generator examines the command line of a running process and automatically generates a configuration
file for wrapping the given application.
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
4 of 21 8/4/2011 4:07 PM
Usage:
wrapper.bat -g <pid> [-d <default configuration file>] <output file>
pid: process id of the process to wrap
<output file> : name of the output configuration file
<default configuration file> : optional input file for defining properties such as logging, restart, scripts etc. which are not available in
the command line of the current process.
NOTE: the configuration generator should not be used for processes which are already wrapped.
NOTE: currently the configuration generator only generates configurations for java applications.
Java Application Launching
The internal workings of application launching and classloading are described here.
Using YAJSW from within a java application
YAJSW may wrap applications through the shell scripts in <yajsw>/bat. These functions may also be embeded within a java application.
Starting a native image
// configuration
Map configuration = new HashMap();
configuration.put("wrapper.image", "notepad.exe");
WrappedProcess w = (WrappedProcess) WrappedProcessFactory.createProcess(configuration);
// initialiase the process
w.init();
// start the process
w.start();
// wait at most 10 sec or until process termination
w.waitFor(10000);
// stop the process
w.stop();
Starting a java application
// global configuration
System.setProperty("wrapper.config", <conf file>);
System.setProperty("wrapper.java.app.mainclass", <main class>); // system properties overwrite properties in conf file.
Map configuration = new HashMap();
WrappedProcess w = (WrappedProcess) WrappedProcessFactory.createProcess(configuration);
/ process specific configuration
w.getLocalConfiguration().setProperty("wrapper.app.parameter.1", "hello");
// initialiase the process
w.init();
// start the process
w.start();
w.waitFor(10000);
// stop the process
w.stop();
Reading the output stream of a wrapped application
WrappedProcess w = (WrappedProcess) WrappedProcessFactory.createProcess(new HashMap());
// process specific configuration
w.getLocalConfiguration().setProperty("wrapper.app.parameter.1", "hello");
// initialiase the process
w.init();
// start the process
w.start();
// a drain warps access to the output and error streams of the wrapped process. The process does not hang if the output is not consumed.
// a drain must be started and stopped
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
5 of 21 8/4/2011 4:07 PM
// the drain maintains a circular buffer
// if since last call to readDrainLine() no new output has been generated then "null" is returned
// if readDrainLine() is not called for a "long time" the buffer may overflow and you may "miss" some of the output
// the drain first consumes the error stream, if no output is available the output stream is consumed
w.startDrain();
System.out.println(w.readDrainLine());
w.stopDrain();
w.waitFor();
Writing the input stream of a wrapped application
WrappedProcess w = (WrappedProcess) WrappedProcessFactory.createProcess(new HashMap());
...
// initialiase the process
w.init();
// start the process
w.start();
// get a print stream to the process
PrintStream out = (PrintStream)w.getOutputStream();
// send some text to System.in of the process
out.println("my password");
Restarting/Stopping the JVM from within a wrapped application
org.rzo.yajsw.app.WrapperJVMMain.WRAPPER_MANAGER.restart();
org.rzo.yajsw.app.WrapperJVMMain.WRAPPER_MANAGER.stop();
Getting a Thread Dump of the wrapped application
WrappedJavaProcess w = ...
w.requestThreadDump();
Installing a service
System.setPropery("wrapper.config", <conf file>);
WrappedService w = new WrappedService();
w.init(); // read in configuration
w.install(); // start the service
Starting a service
WrappedService w = ...
w.init(); // read in configuration
w.start(); // run the service
Stopping a service
WrappedService w = ...
w.init(); // read in configuration
w.stop(); // stop the service
Listening to state change
WrappedProcess w =...
// initialiase the process
w.init();
w.addStateChangeListener(WrappedProcess.STATE_ABORT, new StateChangeListener()
{
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
6 of 21 8/4/2011 4:07 PM
public void stateChange(int newState, int oldState)
{
Script script = ScriptFactory.createScript("scripts/sendMail.gv", "some id", w, new String[{"[email protected]", "process could
not be started"});
script.execute();
});
w.start();
Monitoring java applications
YAJSW implements features helping you to monitor your java applications. Currently the following monitors have been impelemented:
Memory
Deadlocks
Monitoring Heap
to enable set:
wrapper.java.monitor.heap = true
wrapper.java.monitor.heap.threshold.percent = 90
If the current used heap size exceeds 90% of the maximal heap size the following message is printed to System.err:
wrapper.java.monitor.heap: HEAP SIZE
By setting a triffer on this text one can execute actions or scripts.
Example: send an email if the used heap exceeds 90%:
wrapper.java.monitor.heap.threshold.percent = 20
wrapper.filter.trigger.heap.mail=wrapper.java.monitor.heap: HEAP SIZE
wrapper.filter.script.heap.mail=scripts/sendMail.gv
[email protected], Java low on memory set java option -Xmx to a higher value or check for memory
leaks.
Monitoring Memory
to enable set:
wrapper.java.monitor.gc=MYGC: {0\,number\,integer}\, {1\,number\,integer}\, {2\,number\,integer}
The text "MYGC: {0\,number\,integer}\, {1\,number\,integer}\, {2\,number\,integer}" is a java MessageFormat pattern which is formatted
with the following arguments: Used Heap, Minor GC Duration, Full GC Duration.
The formatted text is logged to System.err when the garbage collector has been executed.
A GC duration is 0 if it has not been executed.
You can set your own pattern and write a program which scans the log file to analyze the heap requirements of your applicaiton.
You could also use a trigger and script to write the data to a database, for later display or analysis.(see rdd4j)
Monitoring Deadlocks
to enable set:
wrapper.java.monitor.deadlock = true
When a deadlock is detected the following text is printed to System.err:
wrapper.java.monitor.deadlock: DEADLOCK IN THREADS:
A thread dump of the threads involved is also printed.
By setting a trigger on this text one can execute actions or scripts.
Example: Monitor for deadlocks, display a tray icon message and restart the application if a deadlock is detected:
wrapper.java.monitor.deadlock=true
wrapper.filter.trigger.deadlock.tray=wrapper.java.monitor.deadlock: DEADLOCK IN THREADS:
wrapper.filter.script.deadlock.tray=scripts/trayMessage.gv
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
7 of 21 8/4/2011 4:07 PM
wrapper.filter.script.deadlock.tray.args=Deadlock Detected
wrapper.filter.trigger.deadlock.restart=wrapper.java.monitor.deadlock: DEADLOCK IN THREADS:
wrapper.filter.action.deadlock.restart=RESTART
Timers and Conditions
A timer allows one to automatically start/stop/restart the application at specific times or intervals. If a timer is defined the wrapper service
runs as long as the timer is active. The wrapper uses the Quartz framework to start/stop the application.
Example:
wrapper.timer.RESTART.cron=* * 0/12 * * ?
Starts the process immediatly and restart the process daily at 00:00 and 12:00 h.
A condition is agroovy script which is executed at fixed time intervals or only once. The script controls the start/stop of the application.
YAJSW includes the following sample condition scripts:
timeCondition.gv: This script will make sure that the process is running between the specified times:
Configuration Example:
wrapper.condition.script=scripts/timeCondition.gv
wrapper.condition.script.args=23,1:50
will start the application at 23:00 and will stop it at 1:50 the next day.
commandCondition.gv: This script checks for the presence of a command file. If the file is present the content of the file is read
and the command in the file is executed.
Configuration Example:
wrapper.condition.script=scripts/commandCondition.gv
wrapper.condition.script.args=cmd.txt
wrapper.condition.cycle=1
When using Timers or Conditions the functionality of the start() and stop() methods may be confusing.
The first call to start() will trigger the timer or condition.
If a condition is defined the first call to start() will not start the process. Subsequent calls to start() will start the application.
If a timer is defined the first call to start() will start the application only if the property wrapper.timer.cron.START or wrapper.timer.simple.
<cmd>.FIRST is not defined.
A call to stop() will stop the application.
To cancel the timer use the method stopTimer()
To cancel the condition use the method stopCondition()
JMX Support
JMX Support is available for the wrapper and for the wrapped application.
To activate JMX support on the wrapper:
add the property wrapper.jmx=true to the configuration file.
if port 1099 is not free set wrapper.jmx.rmi.port=<a free port>
To activate authentication the credentials may be defined in the configuration:
wrapper.jmx.rmi.user
wrapper.jmx.rmi.password
To activate JMX support for the wrapped application:
add the property wrapper.java.jmx=true to the configuration file
add the property wrapper.java.additional.<n>=-Dcom.sun.management.jmxremote to the configuration file
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
8 of 21 8/4/2011 4:07 PM
The name of the YAJSW MBeans are:
Wrapper:name=<cosole.title> or <service.name> or "?"
System Tray Support
YAJSW offers support for system tray. That is for displaying a status icon and menue on the desktop.
The java system tray is available only for Sun JDK 1.6 or higher. Since YAJSW requires JDK 1.5 or higher the program will detect if system
tray is supported.
System tray is activated by setting the property wrapper.tray = true
The System Tray Icon is started in a separate process which communicates with the wrapper through netty asynchronous hessian.
The port for communication is boradcasted using multicast discovery.
The System Tray process is automatically started if the application is started as console.
When running the wrapper as a service the tray icon has to be started separately. One may for example, on windows, create a link to start the
try icon from the startup folder.
The process can be started by calling "java -jar wrapper.jar -y <conf file>".
The batch script systemTrayIcon.bat starts the process for the default configuration file.
Per configuration file only a single tray icon process can be started. If a process is started while another process is already running, the
process will exit.
You may define your own icon to be displayed by setting the property wrapper.tray.icon=<full path to image file>.
If not defined, a default icon is used.
File formats supported by java such as jpg, npg, gif can be used.
The icon size is automatically scaled to fit the size required by the OS. The state of the application is displayed by a colored circle on the
icon.
RED == IDLE
GREEN == RUNNING
ORANGE == other (starting, restarting, stopping)
BLACK == OFFLINE (no communication with the wrapper)
The system tray offers menues for starting stopping and restarting the application. These however do not stop the wrapper. The exit wrapper
menue will stop the wrapper. The exit menue will close the Tray Icon.
The console menue will open a window displaying the console output of the application. When the window is closed the application
continues to run.
Using groovy scripts you may display notification messages:
Access the system tray icon:
process.getTrayIcon()
The following methods are available, where caption is the header of the message and message is the content:
TrayIcon.error(caption, message)
TrayIcon.info(caption, message)
TrayIcon.warning(caption, message)
TrayIcon.message(caption, message)
A sample script is provided for displaying an exception in case an exeption is logged on the console.
NOTE: Linux, Solaris:
Currently wrapper.ntservice.interactive is not automatically handled by YAJSW. You will have to make sure that DISPLAY is exported and
xhost + is called.
NOTE: Mac OS X, FreeBSD:
System tray is currently not supported.
Windows services
When starting a windows service the service is displayed as running as soon as the wrapper is up. The wrapper process will then control and
monitor the application.
Stopping a service, depending on the application cleanup time, the wrapper.control property and the defined script properties, may require
extra time. After 2 minutes, the SCM snap-in timeout, a windows 1503 error message is displayed. This message does not mean that the
service is forcibly killed. The service will continue to with the cleanup. Timeouts are controlled by the wrapper using the according
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
9 of 21 8/4/2011 4:07 PM
configuration properties.
Unix/Linux Daemon
YAJSW tries to support users with little or no Unix/Linux knowledge by offering similar functions as for windows services.
YAJSW offers the following functions. These functions are also accessible through the API of WrappedService
-i : install a daemon script
wrapper.daemon.template is a velocity script used to generate the daemon script.
The script is placed in the directory <wrapper.daemon.dir>
The daemon script is named <wrapper.ntservice.name>
-r : remove the daemon script
-t : start the daemon
starting the daemon creates the files <wrapper.pidfile> and <wrapper.java.pidfile>. These are used to stop the daemon or
to check the status of the daemon.
per default these files are named wrapper.<wrapper.ntservice.name>.pid wrapper.java.<wrapper.ntservice.name>.pid
and are placed per default in the directory <wrapper.daemon.pid.dir>
-p : stop the daemon
-q : query the state of the daemon
-qs : silent query of the daemon state
NOTE:
Currently wrapper.ntservices.dependencies is not supported. It will be supported in future release.
See Configuration documentation for further properties.
Mac OS X Daemon
YAJSW tries to support users with little or no Mac OS X knowledge by offering similar functions as for windows services.
For this the launchd utility is used.
YAJSW offers the following functions. These functions are also accessible through the API of WrappedService
-i : install a daemon
wrapper.plist.template is used to generate the plist file.
The plist file is placed in the directory <wrapper.launchd.dir>
The plist file name is: wrapper.<wrapper.ntservice.name>.plist
The label key is: wrapper.<wrapper.ntservice.name>
launchctl load <plist file> is called to install the file
-r : remove the daemon
launchctl unload <plist file> is called
the plist file is removed
-t : start the daemon
launchctl start <plist label> is called
-p : stop the daemon
launchctl stop <plist label> is called
-q : query the state of the daemon
launchctl list is called and the result is analysed to check if the daemon is installed and if it is running
-qs : silent query of the daemon state
NOTE:
currently users are not properly handeled by YAJSW. This will be implemented in future release. For now you will have to execute the scripts
within a user which has the required rights.
NOTE:
Currently wrapper.ntservices.dependencies is not supported. It will be supported in future release.
Scripts
YAJSW supports shell (.bat, .sh) and groovy (.gv, .groovy) scripts.
Scripts may either be wrapped or they may be invoked from within the wrapper triggered by state changes or by matching expressions to the
console output or as conditions which may control job executions.
Here we describe scripts which are executed on state change or triggered by console output or as conditions.
Wrapping groovy scripts is described in the sequel.
A builder for easy interface to YAJSW from within groovy scripts is also described later.
Per default the scripts are placed in the ./scripts folder.
Shell Scripts
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
10 of 21 8/4/2011 4:07 PM
Shell scripts are called with the following arguments:
id
<n> from wrapper.filter.script.<n>
state
the current state of WrappedProcess, defined in Constants.STATE_*
count
the number of failed invocations
pid
the pid of the process. Negative if the process is not running
exit code
exit code of the process. Negative if the process has not exited
console line
the output line of the console, in case the script was triggered by a filter or a regular expression
args
list of arguments are defined in the .args property
Groovy Scripts
Groovy scripts offer much more flexibility and enable calls to the WrappedProcess.
Groovy scripts are compiled and executed within the JVM of the wrapper. They are thus highly performat and maintain their bindings
inbetween calls.
Grooy scripts are executed with the following default bindings:
args
arguments defined in the .args property
callCount
counter of script invocation, starting with 0.
Note: When the script is first called, no user defined variables are bound in the script. callCount can be used to define the
required variables
Example: if (callCount == 0) myVar = 0
id
<n> from wrapper.filter.script.<n>
state
the current state of WrappedProcess, defined in Constants.STATE_*
count
the number of failed invocations
pid
the pid of the process. Negative if the process is not running
exitCode
exit code of the process. Negative if the process has not exited
line
the output line of the console, in case the script was triggered by a filter or a regular expression
process
WrappedProcess
context
a static map, allowing to share data between scripts
Sample Scripts
The following sample groovy scripts have been implemented. Refer to the script file for documentation on how to use it. Refer to the scripts
folder for further scripts.
sendMail.gv
send an email
snmpTrap.gv
send an snmp trap
trayMessage.gv
display a message on the system tray.
fileCondition.gv
make sure the process is running depending on existance of an achor file
timeCondition.gv
make sure the process is running in a time interval
commandCondition.gv
implements the functionality for wrapper.commandfile property.
Example: Send an email and show a system tray message if an exception is logged:
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
11 of 21 8/4/2011 4:07 PM
add the following properties to wrapper.conf file:
wrapper.filter.trigger.exception.mail=Exception
wrapper.filter.script.exception.mail=scripts/sendMail.gv
[email protected], YAJSW exception, exception found in console output please check the log
file
wrapper.filter.trigger.exception.tray=Exception
wrapper.filter.script.exception.tray=scripts/trayMessage.gv
wrapper.filter.script.exception.tray.args=Exception
Condition Scripts
Condition scripts are scripts executed cyclically. If a condition is defined the call to wrapper.bat -c or wrapper.bat -t will trigger the condition
script but will not start the process. The process is started and stopped within the script by calling process.start() or process.stop()
Testing a script
In order to test a script and its configuration without running an application and waiting for it to trigger:
runScript.bat <configuration file> <script> [<count>]
This will search for the script and will determine its arguments in the configuration. It will then create a WrappedProcess, but will not start it,
and will execute the script <count> times. Default count is 1.
Example:
runScript.bat conf/wrapper.conf scripts/sendMail.gv
MSCS Cluster Aware Wrapper
YAJSW may be configured to be MSCS cluster aware.
The configuration property wrapper.windows.cluster.script sets a script which is called on first call to WrappedService.start() and when the
active node of the cluster changes. Within the script one may define actions which are executed when the active node changes. The sample
script cluster.gv enables the application only on the active node.
NOTE: setting this property on none clustered nodes will crash the JVM.
Windows Session0 Isolation
As of Windows Vista it is, per default, not possible to run interactive services, that is services which open a user interface window or a system
tray icon.
If you want to run your service without change you will need a logged on user. You can:
set your computer to automatically log-on a user on boot using a tool such as Sysinternals Autologon
set in the configuration file: wrapper.ntservice.logon_active_session = true, YAJSW will wait for the user to log on and will logon the
application to that user
and :wrapper.ntservice.desktop=WinSta0\\Default, YAJSW will "associate" the application with the default desktop
and: wrapper.ntservice.dependency.1=LanmanServer, the service will start after network is available.
and: wrapper.startup.timeout=300, time for the user to log-on and for the application to startup.
NOTE: using this feature can expose your computer to the shatter attack security risk.
OS Users
YAJSW consists of 2 processes: The wrapper (controller) and the wrapped application.
Whereas the controller requires rights to open a server socket and write to log files, this may not be appropriate for the wrapped application.
The controller should therefore be started as a privileged user, generally root on Linux or administrator or system on Windows.
The application can be started on a different user. The user is defined by the property wrapper.app.account the according password, if
required, is defined by wrapper.app.password YAJSW checks if the current user of the controller is the application user. If not, the user is
changed.
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
12 of 21 8/4/2011 4:07 PM
NOTE Windows:
On MS-windows, per default, if not configured otherwise services are started under the SYSTEM account.
On windows we are using the function CreateProcessAsUserW . This requires the SE_ASSIGNPRIMARYTOKEN_NAME and
SE_INCREASE_QUOTA_NAME user rights.
We are not using CreateProcessWithLogonW because the command line length is limited to 1024 chars, which may be too short for java
applications.
The password is defined by the property wrapper.ntservice.password.
If the password is defined in the configuration file then it is not visible in the command line of the application nor in the windows services
GUI .
NOTE Linux:
On Linux we use the functions setreuid and setregid. This is available only on systems with the _POSIX_SAVED_IDS feature.
No password is required for changing the user.
One may define the user and group: wrapper.app.account=<group>\\<user>
NOTE JSW:
Conform with JSW wrapper.ntservice.account is used only for windows services and sets the user of the controller when it runs as a service.
Per default this is the System user.
Entering passwords
User account names and passwords are defined in the wrapper configuration. However for security reasons one may require that the
password be entered by the user who is installing/starting the application. This can be achieved with groovy scripting in the configuration file.
YAJSW offers 2 utilities to get user input. You may implement your own groovy scripts for this or use the available utilities:
wrapper.ntservice.password = ${util.inquireCLI('please enter password for winods service user')}
wrapper.app.password = ${util.inquireTryIcon('please enter password for winods service user')}
util.inquireCLI(String) prints the given message to the wrapper process console and waits for the user input.
util.inquireTryIcon(String) displays the given message on the system tray icon and waits for the user input.The user will have to click the
respond button in the tray icon menue and enter the required data.
In general one will use CLI for the service password and tray icon for getting the application user password if the application is supposed to
run as a service. When the application is started as a service there is no CLI console to enter the data.
NOTE: groovy scripting and the implemented utilities can be used not only for passwords but for all other configuration properties.
YAJSW lib folder
If you include YAJSW with your own distribution you may not require all features. Thus you may reduce the size of the distribution by
including only libraries required for your functions.
To help with this the third party libraries have been grouped into the following folders:
core
The minimal set of libraries required.
If a core library is missing an error is logged.
extensions
Libraries required for extended functionalities
If an extension library is missing, no error is logged. However an exception will occur if the extension is missing
groovy
Libraries required within groovy scripts. These are loaded when a groovy script is instatiated.
A description of the libraries and corresponding functions is found in the ReadMe.txt file in the according folder.
Wrapper process java options
The java options for the wrapper are set in the shell script setenv.bat.
The java options for the service are set in the configuration file with the properties wrapper.ntservice.additional.<n>.
The memory requirements of the wrapper process are relatively low and are constant. They may vary in case groovy scripts are used and
they depend on the operating system.
On windows the following settings are recommended:
Setting in the configuration file:
wrapper.ntservice.additional.1 = -Xmx5m
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
13 of 21 8/4/2011 4:07 PM
wrapper.ntservice.additional.2 = -server
Setting in the script setenv.bat:
Wrapping groovy scripts
Here a configuration sample for wrapping groovy scripts:
wrapper.helloworld_groovy.conf:
# the groovy file to be executed
wrapper.groovy=scripts/helloworld.gv
# the required jar files
wrapper.java.classpath.1=lib/extended/groovy/*.jar
# Name of the service
wrapper.ntservice.name = groovy_helloworld_service
# Display name of the service
wrapper.ntservice.displayname = groovy_helloworld_service
# Description of the service
wrapper.ntservice.description = Sample groovy script
Here the shell commands to install the script as a service and to start it
rem install it as a service
java -jar wrapper.jar -i conf/wrapper.helloworld_groovy.conf
rem start the service
java -jar wrapper.jar -t conf/wrapper.helloworld_groovy.conf
YAJSW groovified: WrapperBuilder
YAJSW can be embeded in groovy scripts.
Here an example for a groovy script to install tomcat as a service and to restart tomcat daily at 00:00 h
Note that there are different way to implement this with YAJSW.
Here will install 2 services: one for running tomcat, the other for running a groovy script which will install/start/stop tomcat
The configuration file for running tomcat:
Note that we could do the complete configuration within the groovy script. However it is better to separate configuration and logic.
wrapper.tomcat.conf:
# YAJSW: Application main class
wrapper.java.app.mainclass = org.apache.catalina.startup.Bootstrap
# working directory. This could be a system variable or could be set in the groovy script
wrapper.working.dir = ${CATALINA_HOME}
# classpath
wrapper.java.classpath.1 = lib/*.jar
wrapper.java.classpath.2 = bin/bootstrap.jar
# additional options
wrapper.java.additional.1 = -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
wrapper.java.additional.2 = -Djava.util.logging.config.file=conf/logging.properties
wrapper.java.additional.3 = -Djava.endorsed.dirs=endorsed
wrapper.java.additional.4 = -Dcatalina.base=.
wrapper.java.additional.5 = -Dcatalina.home=.
wrapper.java.additional.6 = -Djava.io.tmpdir=temp
# restart tomcat if it crashes
wrapper.on_exit.default=RESTART
#restart tomcat if out of memory
wrapper.trigger.1=java.lang.OutOfMemoryError
wrapper.trigger.action=RESTART
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
14 of 21 8/4/2011 4:07 PM
# Name of the service
wrapper.ntservice.name = Tomcat
# Display name of the service
wrapper.ntservice.displayname = Tomcat
# Description of the service
wrapper.ntservice.description = Tomcat
The script for installing and restarting tomcat
restart_tomcat.gv
/*
* script for restarting the tomcat service
*/
import org.rzo.yajsw.groovy.*
// get a wrapper builder
builder = new WrapperBuilder()
// set the configuration file
builder."wrapper.config" = "conf/wrapper.tomcat.conf"
// set catalina home here if no system env var is available
//builder."CATALINA_HOME"=
// get a service for starting tomcat
// first set the app parameter
builder."wrapper.app.parameter.1" = "start"
// now get a service
tomcatService = builder.service()
// get a process for stopping tomcat
// first set the app parameter
builder."wrapper.app.parameter.1" = "stop"
// now get a process
tomcatStopProcess = builder.stop()
// stop tomcat: equivalent to a call to catalina.bat stop
tomcatStopProcess.start()
// wait for this process to terminate
tomcatStopProcess.waitFor()
if (tomcatStopProcess.exitCode == 0)
println "tomcat stopped"
// check if the tomcat service is installed
if (!tomcatService.isInstalled())
tomcatService.install()
// start the service
tomcatService.start()
if (tomcatService.isRunning())
println "tomcat started"
Next we need a configuration file for running the above script daily at 00:00 h
wrapper.restart_tomcat_gv.conf
# the groovy file to be executed
wrapper.groovy=scripts/restart_tomcat.gv
# the required jar files
wrapper.java.classpath.1=lib/extended/groovy/*.jar
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
15 of 21 8/4/2011 4:07 PM
# Name of the service
wrapper.ntservice.name = restart_tomcat_gv
# Display name of the service
wrapper.ntservice.displayname = restart_tomcat_gv
# Description of the service
wrapper.ntservice.description = script to restart tomcat
# cron timer
wrapper.timer.START.cron=0 0 0 * * ?
At last we install the above script as a service and start it
rem install it as a service
java -jar wrapper.jar -i conf/wrapper.restart_tomcat_gv.conf
rem start the service
java -jar wrapper.jar -t conf/wrapper.restart_tomcat_gv.conf
Further samples for running the nutch crawler, nutch tomcat and nutch with solr are found in the conf and scripts folders.
Building YAJSW
The source code is included in the download.
Go to the folder <yajsw>/build/gradle.
Execute gradlew.
Network Launching of Applications - Experimental
YAJSW offers a functionality similar to java web start allowing users to run applications which are not or not completely available on the
current computer. We may for example use jar files from a maven repository or from subversion. With YAJSW we however assume that we
are in an enterprise environment. Therefore we do not implement security features such as sandbox. Nor do we, for now, implement features
such as splash screens or desktop icons. On the other hand we support other file systems such as local files, HTTP, FTP, SFTP, HTTPS,
WebDav, Samba, Subversion, SMTP, ZIP, etc. For more details on the supported file systems please refer to commons vfs.
The property wrapper.codebase defines the root base. All relative files specified in wrapper.resource or wrapper.java.classpath are supposed
to be relative to this root.
Example:
wrapper.codebase=http://mysite.com/application-files
or
wrapper.codebase=c:/dev
The property wrapper.cache defines the path to the local cache. All remote files are copied to this directory. On application startup we
syncrhonize the cache with the remote files by checking the file lastModified attribute.
The boolean property wrapper.cache.local indicates if local files should be copied to the cache. This property is false per default.
Example:
wrapper.cache=${java.io.tmpdir}/myapp
wrapper.cache.local=true
NOTE: lazy download is not supported. All specified files are downloaded to the cache folder.
NOTE: if the folder does not exist it is created.
NOTE: if no cache is defined /yajsw_cache is used as default cache folder
The application may require more resources than just the classpath. These files (resources) are specified with the properties
wapper.resource.<n> and are downloaded to the
Example:
wrapper.resource.images = images/*.*
wrapper.resource.lib.1=libs/mylib.dll
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
16 of 21 8/4/2011 4:07 PM
are downloaded to:
${java.io.tmpdir}/myapp/images and ${java.io.tmpdir}/myapp/libs
Classpath files may be relative or absolute.
Example:
wrapper.java.classpath.1=lib/test.jar
warpper.java.classpath.2=http://someothersite.com/lib2/test2.jar
are downloaded to
${java.io.tmpdir}/myapp/lib/test.jar and ${java.io.tmpdir}/myapp/lib2/test2.jar
Configuration files may also be loaded remotely.
Example:
start the application as console
java -jar wrapper.jar -c http//mysite.com/test/wrapper.conf
install the application
java -jar wrapper.jar -i http//mysite.com/test/wrapper.conf
Within a conf file include files are absolute or relative. Relative locations are assumed relative to the parent configuration file.
Example:
include = wrapper_stop.conf
include = http//someothersite.com/conf2.conf
will include the cofiguration files:
http//mysite.com/test/wrapper_stop.conf and http//someothersite.com/conf2.conf
Platform specific configuration can be defined in platform specific include configuratoin files:
Example:
include=${os.name}.{os.arch}.libs.conf
On windows XP, x86 YAJSW will include the following file:
windows XP.x86.libs.conf
To launch an application we proceed as follows:
load the configuration file to memory.
if the configuration file is a remote file create a local interpolated copy, in which all includes have been resolved
copy files to the cache if these are not in the cache or have different lastModified property
execute the wrapper command (-c, -i, -u, -t, -p)
NOTE: currently the remote resources are downloaded only when the service is installed. When the service is started the jar files from the
cache are used to start the application. To check for a new version of the application you will have to reinstall the service.
NOTE: currently the application is not started if the remote host is not accessible, even if the files have been previously downloaded.
NOTE: some transport protocols, such as webdav or ftp support folder listing and therefore also support wild cards for classpath files.
NOTE: setting http proxy: java -jar wrapper.jar -Dhttp.proxyHost=<myproxy> -Dhttp.proxyPort=8080 -c http//mysite.com
/test/wrapper.conf
NOTE: for now only http proxy settings is supported. In future other proxy settings will be supported.
NOTE: proxy exclusion list is currently not supported.
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
17 of 21 8/4/2011 4:07 PM
NOTE: A batch script, remoteLauchTomcatDemo.bat, is provided to test this feature. This will wrap a tomcat which is installed on my test
server (eprognos.com) and will start it localy on port 8081. The configuration file is http://eprognos.com/webdav/wrapper.tomcat.conf
This is a new feature. If you have suggestions or further requirements on how to integrate the wrapper functionality with remote launching,
please post your ideas on the project forum.
Wrapping JNLP - Experimental
A call to
java -jar wrapper.jar -c http://java.sun.com/javase/technologies/desktop/javawebstart/apps/draw.jnlp
will parse the jnlp file, convert it to a wrapper configuration file and will launch the application as described in Network Launching.
java -jar wrapper.jar -i http://java.sun.com/javase/technologies/desktop/javawebstart/apps/draw.jnlp
will parse the jnlp file, convert it to a wrapper configuration file save the file to the cache and install a service which will use the
configuration file to launch the application.
However, the draw application requires the file javaws.jar, which is not defined in draw.jnlp. This is achieved by adding some local
configuration as follows:
java -jar wrapper.jar -c -d conf/wrapper.javaws.conf http://java.sun.com/javase/technologies/desktop/javawebstart/apps/draw.jnlp
Currently only "simple" jnlp configurations are supported. The following jnlp tags/attributes are NOT supported:
External jnlp
OS, arch, locale depdent configuration
Applets
package, extension, j2se, nativelib, component-desc, installer-desc, part, lazy, <jar .. main-class>, information
If you require one of these features please post a message on the project forum or tracker.
NOTE: -d <remote file> is supported.
Java Web Start Support - Experimental - Currently only for windows
Installing the same service on multiple servers is a pain. YAJSW may help by providing a java webstart bootstrap. This will invoke a jar file
which will download YAJSW and will call either runConsole or installService.
The following live demo will download YAJSW which will download and start a tomcat server
Note: for windows 7, Vista & co: you will need to run your browser as administrator (right click -> run as administrator) in order to be able to
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
18 of 21 8/4/2011 4:07 PM
start/install services.
In a future release this feature will be used to drive yajsw tests on multiple platforms.
For this function the following files are required:
wrapper.jnlp : please set the following arguments:
<argument>path-to-yajsw-folder-on-the-server</argument>
<argument>destination-folder-on-local-computer</argument>
<argument>yajsw-command (c,i,t,y)</argument>
<argument>remote-configuration-of-application</argument>
<argument>nogui</argument> (optional)
If you do not want yajsw to display a gui add nogui as last argument.
If a gui is enabeled you may leave certain arguments empty and have the user enter them.
wrapperWS.jar
this is the file which is executed by java web start. The file has been signed as described here. You may decide to sign it with your
credentionals. The keystore and batch files for signing are found in the build folder
remote-configuration-of-application
this file is the file used to remotely sart the applicaition as described here.
Services Manager - Experimental - Currently only for windows
This new feature is currently implemented for windows only. If you would like to have this feature for other frameworks please post on the
project forum.
Managing services on multiple servers in a multi-platform environment may be cumbersome. The YAJSW Services Manager allows one to :
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
19 of 21 8/4/2011 4:07 PM
View services and YAJSW console processes on multiple hosts: Select one or multiple hosts and click ">>" to view their services. Click
"<<" to remove them from the services table.
Hosts are add using the "+" button. And removed using the "-" file.
All settings are saved in the "ServiceManager.ser" file.
Start/Stop services and YAJSW console processes: Select one or more services and click start/stop
Install/Uninstall YAJSW services: Select one or more services and click uninstall. To install click install enter the path to a YAJSW
configuration select the hosts and click install.
To update YAJSW console applications, the according wrapper must be running. Select the console application and click the "reload
Console App" button.
To maintain an overview of the services you are interested in: select the services you do not want to see and click "<<" to hide them.
To add them to the services list click ">>".
The services manager consists of a server and a client process.
The server process must be running on all managed hosts. To run/install the server use the according scripts in the <yajsw>/bat folder
To start the user interface use the script under <yajsw>/bat folder.
You may also start the server and client using java web start:
start server using java web start
start client using java web start
NOTE: the client server communication is implemented through asynchronous hessian rpc. This will hopefully be integrated in the jboss netty
project.
Android Services Manager - experimental
This android app allows one to monitor services and daemons on multiple servers on an android mobile phone.
The android application connects to a single server process called the ServiceManagerHub. The hub server, using multicast discovery,
connects to the Services Manager Server processes in the network.
The android application connects to the hub process, retrieves the data and displays it on the smartphone.
Currently the app implements 2 views:
List of hosts : RED no connection to the Services Manager Server on the host, GREEN host is connected
List of services: RED: service is not running, GREEN: service is running, YELLOW: YAJSW wrapper is running, but not the
application.
Swipe the screen to change the view.
In future releases further functions will be implemented.
Feedback is welcome.
Third party Libraries
Commons Configuration: Configuration is done using commons configuration, thus allowing a richer and more flexible configuration. YAJSW
additionaly supports OS environment variables and java system properties.
JNA : The complete implementation is thus in java instead of C and will be available on all platforms for which JNA will be available.
Jboss Netty : TCP/IP inter-process communication is done using jboss netty. This makes the implementation of the communication readable
and easily adaptable.
Commons CLI 2 : Command Line Interface can thus be easily extended.
Quatrz : Job scheduling
JREXX : High Performance regular expression matching, as an alternative for filter matching
Groovy : for scripts.
JavaMail : used for sending emails (in sendMail.gv)
Launch4j : for generating wrapper.exe on windows
Joda: for easier handling of time and date (used in timeCondition.gv)
Tango Icon Library: Icons for the system tray icon
SNMP4J: for sending snmp traps (in snmpTrap.gv)
famfamfam : icons
Abeille : Gui forms designer
JGoodies FormLayout : Layout used by abeille
Apache Velocity : java template engine
Commons VFS : Virtual File System for downloading files in network launching
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
20 of 21 8/4/2011 4:07 PM
testNG unit test framework used with groovy
jMock mock objects framework for unit tests
GlazedLists: GUI grid framework used in ServiceManagerClient
Hessian: Hessian is a compact binary protocol for connecting web services.
Gradle: A build tool alternative to maven, ant & co.
- Ron
YAJSW - Yet Another Java Service Wrapper - Introduction http://yajsw.sourceforge.net/
21 of 21 8/4/2011 4:07 PM