Migrating from JSW

## Migrating from JSW to YAJSW

1. Differences between JSW and YAJSW
   1. 1. 1. Visible Console
         2. Simple Configuration
         3. Integration Methods
         4. Wrapper/Application coupling
         5. Application termination
         6. Additional functions
         7. One wrapper multiple applications
         8. Posix daemons
         9. Application main class
         10. Logging
         11. Space in paths
         12. Wrapper memory requirements
      2. Launching the application
         1. Command line interface
      3. Migrating from JSW integration method 1
      4. Migrating from JSW integration method 2
      5. Migrating from JSW integration method 3
      6. Migrating from JSW integration method 4

### 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>

###