Migrating from JSW

Migrating from JSW to YAJSW

Differences between JSW and YAJSW

Differences between JSW and YAJSW

Before starting the migration you should consider the main differences between JSW and YAJSW

Visible Console

In JSW, as YAJSW we have 2 processes, the wrapped application and the controller or wrapper process. With JSW only the wrapper process has a console. With YAJSW you may have a visible console for both the wrapper and the application. This has the advantage, that you may type in data directly into the application console. You may also start the wrapper with javaw. This has the advantage, that the wrapper console is invisible and the application can be automatically restarted if the console of the application is accidentally closed.

Simple Configuration

With JSW you have to include in the configuration the jar and the native libraries of the wrapper. With YAJSW this part of the configuration is transparent. The wrapper will take care of this. In the configuration you just have to include the configuration of your application. You do not have to deal with the wrapper.

YAJSW also supports wild cards for classpath.

YAJSW allows for configuration within a groovy script. Within groovy the configuration becomes dynamic and platform independent.

Environment Variables

JSW supports references to environment variables with the windows notation %JAVA_HOME%.
YAJSW supports references to environment variables with the groovy notation ${JAVA_HOME}.

NOTE: In general YAJSW variables are case sensitive, except for windows environment variables, where all variables are converted to lower case. For example to access the Path variable use ${path}.

JSW enables the definition of environment variables within the configuration file using set.EXTERN=123 and set.default.
YAJSW support the definition of variables as in a groovy script: EXTERN=123
YAJSW does not support set.default.

JSW supports predefined default environment variables such as WRAPPER_ARCH
In YAJSW these can be accessed by accessing the java system properties. Thus for example %WRAPPER_ARCH% should be replaced by ${os.arch}

JSW supports predefined variable definitions which can be used for event variable definitions such as WRAPPER_NAME
In YAJSW all configuration properties can be accessed for the definition of all configuration properties by dereferencing. Thus %WRAPPER_NAME% should be replaced by ${wrapper.name}
YAJSW currently does not support WRAPPER_EVENT_ variables. Some of these variables are accessible within scripts by accessing the process variable

JSW also uses set.VAR=VALUE to set the environment variables for the application process.
with YAJSW process environment variable are set with the wrapper.app.env.<var> configuration properties.
Example:
set.PATH = c:/temp should be changed to wrapper.app.env.path = c:\\temp

Integration Methods

JSW comes with 4 integration methods, one of which requires programming. YAJSW has just one integration method. The other integration methods are handeld by configuration.

Wrapper/Application coupling

With JSW stopping the wrapper will cause the application to stop. There are however cases where the application should continue to run even when the wrapper is stopped and vice versa. With YAJSW you may configure how the applications are coupled.

Application termination

There exist applications which should continue to run even if the main method of the application terminates or if the main method throws an exception. With YAJSW you can configure if the application should continue to run (this is the case when the application has none-daemon threads) or should be terminated. You may also define the exit code.

Additional functions

JSW offers additional functions such as command file, anchor file, email etc. For new functions or if functional changes are needed, the JSW has to be extended. In YAJSW these functions have been implemented with groovy scripts. YAJSW comes with sample scripts for sending mails, anchor file, command file and sending snmp traps. You can easily adapt these scripts to your requirements and you may add new scripts without having to build the YAJSW code.

One wrapper multiple applications

With JSW we are bound to one wrapper per application. With YAJSW the wrapper can be integrated within a java application or a groovy script. We may thus have a groovy script or java application which runs and monitors multiple applications. The wrapper exe may also be invoked with multiple configuration files.

Posix daemons

JSW comes with scripts for running applications as daemons. This requires different scripts for different platforms. YAJSW offers the same functions for all platforms. Windows service configuration properties are also used for other platforms. The differences are handeld by configuration properties.

Application main class

Configuration of the main class to be executed depends in JSW on the integration method. With YAJSW the java main class is defined in the configuration. For compatiblity if none is found in the configuration YAJSW assumes that the java main class is the first argument.

Logging

JSW grabs the application output on the OS level. For this reason The application will hang if the wrapper is stopped because the output stream is not consumed. For java applications YAJSW grabs the output on the java level and writes it to a memory mapped file which is used as a circular buffer. We thus make sure, that the application does not hang even if the wrapper is not consuming the output. This however has the disadvantage, that errors reported by the java launcher are not logged by the wrapper.

Space in paths

YAJSW allows for spaces in paths and for quotes in java options or arguments. For this reason YAJSW requires for JVM options and for arguments to be either quoted or to be in separate properties.
Where as JSW would allow

wrapper.java.additional.1 = -Xms512m -Xmx512m -XX:MaxPermSize=256m

YAJSW requires:

wrapper.java.additional.1a = -Xms512m
wrapper.java.additional.1b = -Xmx512m
wrapper.java.additional.1c = -XX:MaxPermSize=256m

Wrapper memory requirements

The flexibility of YAJSW comes at a price. Using java for the wrapper process has many advantages. However we pay the java price of higher memory footprint. Whereas the JSW wrapper requires only a few k of memory, the minimal virtual memory requirement of YAJSW is 90 MB and 40 MB physical memory. The value varies depending on the OS and the functions.

Launching the application

YAJSW comes with sample scripts. Within the setenv.bat / setenv.sh you may set java for the wrapper process, the jvm options for the wrapper and the default configuration file. You may however easily adapt these scripts to your requirements.
Note that YAJSW requires java 1.5 or higher.

Command line interface

NOTE:
YAJSW assumes that the directory structure is maintained. That is, the location of the wrapper.jar is assumed to be the home directory of YAJSW. The relative location and structure of the lib folder must be maintained.

Go to the YAJSW home directory and call

java -jar wrapper.jar

This will display the usage information.
The main commands are:

run as console:

java -jar wrapper.jar -c <configuration file> <configuration file> ...

install a service or daemon:

java -jar wrapper.jar -i <configuration file> <configuration file> ...

uninstall a service or daemon

java -jar wrapper.jar -u <configuration file>

start a service or daemon

java -jar wrapper.jar -t <configuration file>

stop a service or daemon

java -jar wrapper.jar -p <configuration file>

Migrating from JSW integration method 1

Copy your existing configuration file to <YAJSW>/conf/. We will refer to this file as <conf>
Edit the configuration file:

remove wrapper.java.classpath.1=<path>/wrapper.jar
remove wrapper.java.classpath.2=<jdk path>\lib\tools.jar
remove wrapper.java.library.path.1=<path to wrapper native lib>
replace wrapper.app.parameter.1=<application main class> with wrapper.java.app.mainclass=<application main class>
remove wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
replace all "\" with either "\\" or "/"
replace all "," with "\,"
eventually split java options to separate properties
eventually set wrapper.working.dir = <working dir of application>
eventually replace environment variables by the YAJSW notation

Go to <YAJSW> folder and run the application as console by calling:

java -jar wrapper.jar -c conf/<conf>

Migrating from JSW integration method 2

Copy your existing configuration file to YAJSW/conf/. We will refer to this file as <conf>
Edit the configuration file:

remove wrapper.java.classpath.1=<path>/wrapper.jar
remove wrapper.java.classpath.2=<jdk path>\lib\tools.jar
remove wrapper.java.library.path.1=<path to wrapper native lib>
replace wrapper.app.parameter.<n>=<application main class> with wrapper.java.app.mainclass=<application main class>
remove wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperStartStopApp
remove wrapper.app.parameter.2=<arg count>
remove all properties for the stop application these will be defined in another configuration file:

remove wrapper.app.parameter.<n>=<stop application main class>
remove wrapper.app.parameter.<n>=<boolean>
remove wrapper.app.parameter.<n>=<stop application arg count>
remove wrapper.app.parameter.<n>=<stop application argument>

replace all "\" with either "\\" or "/"
replace all "," with "\,"
add wrapper.stop.conf=stop_<conf>
eventually split java options to separate properties
eventually set wrapper.working.dir = <working dir of application>
eventually replace environment variables by the YAJSW notation

Create a new file stop_<conf> with the following content:

wrapper.app.parameter.1=<stop application argument>
wrapper.stopper = true
include = <conf>

Go to YAJSW folder and run the application as console by calling:

java -jar wrapper.jar -c conf/<conf>

Try stopping the application by calling

java -jar wrapper.jar -c conf/stop_<conf>

Migrating from JSW integration method 3

Not Yet Implemented

Migrating from JSW integration method 4

Copy your existing configuration file to <YAJSW>/conf/. We will refer to this file as <conf>
Edit the configuration file:

remove wrapper.java.classpath.1=<path>/wrapper.jar
remove wrapper.java.classpath.2=<jdk path>\lib\tools.jar
remove wrapper.java.library.path.1=<path to wrapper native lib>
remove wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperJarApp
replace wrapper.app.parameter.1=<jar file> with wrapper.java.app.jar=<jar file>
remove wrapper.java.mainclass=org.tanukisoftware.wrapper.WrapperSimpleApp
replace all "\" with either "\\" or "/"
replace all "," with "\,"
eventually split java options to separate properties
eventually set wrapper.working.dir = <working dir of application>
eventually replace environment variables by the YAJSW notation

Go to <YAJSW> folder and run the application as console by calling:

java -jar wrapper.jar -c conf/<conf>