 |
Documentation
Users
Download
Get Involved
Hosted by:
|  |  |  |
API Overview
Overview of the Wrapper's Java API |
The Java-side API for Wrapper is quite simple and can be run in one of three
modes.
Using the WrapperSimpleApp class |
The first is to use the WrapperSimpleApp class to launch your Java
application with out any modifications. This class handles all
communication with the native wrapper and simply launches your
application by calling its main method as would be done from the
command line.
The drawback to this method is that when your service is stopped, it
is killed as if the user had hit CTRL-C in the console. This means
that your application may not be able to shut itself down cleanly.
One option that you have is to register a shutdown hook. A shutdown
hook is a thread that is run when a JVM shuts down normally. See the
java.lang.Runtime.addShutdownHook javadocs for more information.
The benefit is that almost any Java application will work as is using
this class. All you need to do is set the following properties in your
wrapper.conf file. They are described in detail in the
Configuration Overview.
# Set the main class to be the WrapperSimpleApp
wrapper.java.mainclass=com.silveregg.wrapper.WrapperSimpleApp
# Set the first application parameter to the name of the class whose main method
# is to be launched. Additional parameters come after this one.
wrapper.app.parameter.1=com.widgetsrus.MyAppMain
wrapper.app.parameter.2=parameter1
wrapper.app.parameter.3=parameter2
# Be sure to set your classpath.
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar
|
In most cases, that should be it. Your application can now be launched
using the scripts found in the
Launch Overview.
|
Using the WrapperStartStopApp class |
The second is to use the WrapperStartStopApp class to launch your
Java application, once again, without any modifications. This class
is useful for applications which are designed to be shutdown externally.
An example is Tomcat4, shown in the
Samples section of this
documentation.
The WrapperStartStopApp actually requires that two seperate Main classes
be configured. The first is to start the application, just like is done
with the WrapperSimpleApp above. The second class is used to stop the
application.
The most common case is for applications which are modeled after unix
services. An application is launched and then it is killed using a
command sent via a socket connection from another application instance.
This helper class was implemented is a way that does not require any
special feature from the Wrapper or its configuration file. Both
the start and stop class, along with all of their parameters are
specified in the parameters to the WrapperStartStopApp main method.
In conjunction with the Wrapper, it will then make sure that the main
method of the start class is called at startup, and that the main
method of the stop class is called at shutdown.
To configure the Wrapper to use the WrapperStartStopApp to control your
application, you must set the following properties in your wrapper.conf
file. They are described in detail in the
Configuration Overview.
# Set the main class to be the WrapperStartStopApp
wrapper.java.mainclass=com.silveregg.wrapper.WrapperStartStopApp
# Set the first application parameter to the name of the class whose main method
# is to be launched. The class is followed by the number of parameters to be passed
# to the main method. Then the actual parameters.
wrapper.app.parameter.1=com.widgetsrus.MyAppStart
wrapper.app.parameter.2=2
wrapper.app.parameter.3=startparameter1
wrapper.app.parameter.4=startparameter2
# The start parameters are followed by the name of the class whose main method
# is to be called to stop the application. The class is followed by a flag which
# controls whether or not the Wrapper should wait for all non daemon threads to
# complete before exiting the JVM. The flag is followed by the number of
# parameters to be passed to the main method. Then the actual parameters.
wrapper.app.parameter.5=com.widgetsrus.MyAppStop
wrapper.app.parameter.6=true
wrapper.app.parameter.7=1
wrapper.app.parameter.8=stopparameter1
# Be sure to set your classpath.
wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=../lib/myapp.jar
|
That should be all that you have to do. com.widgetsrus.MyAppStart.main will be
called at startup and com.widgetsrus.MyAppStop.main will be called at shutdown.
|
Implement the WrapperListener interface |
The third method is to have your application implement the
WrapperListener interface. This interface provides three methods
used to inform your application when it should start and stop as well
as when a system control event takes place (for example, the user
hitting CTRL-C, or logging out under windows)
The WrapperListener class has the following methods.
public interface WrapperListener {
/**
* The start method is called when the WrapperManager is signaled by the
* native wrapper code that it can start its application. This
* method call is expected to return, so a new thread should be launched
* if necessary.
* If there are any problems, then an Integer should be returned, set to
* the desired exit code. If the application should continue,
* return null.
*/
Integer start(String[] args);
/**
* Called when the application is shutting down. The Wrapper assumes that
* this method will return fairly quickly. If the shutdown code code
* could potentially take a long time, then WrapperManager.stopping()
* should be called to extend the timeout period. If for some reason,
* the stop method can not return, then it must call
* WrapperManager.stopped() to avoid warning messages from the Wrapper.
*
* @param exitCode The suggested exit code that will be returned to the OS
* when the JVM exits.
*
* @return The exit code to actually return to the OS. In most cases, this
* should just be the value of exitCode, however the user code has
* the option of changing the exit code if there are any problems
* during shutdown.
*/
int stop(int exitCode);
/**
* Called whenever the native wrapper code traps a system control signal
* against the Java process. It is up to the callback to take any actions
* necessary. Possible values are: WrapperManager.WRAPPER_CTRL_C_EVENT,
* WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, or
* WRAPPER_CTRL_SHUTDOWN_EVENT
*/
void controlEvent(int event);
}
|
An application implementing the WrapperListener should not directly
start the application in the main method. Everything that would
normally be in the main method should be moved into the start method.
The main method should simply contain the following code:
public class MyApp implements WrapperListener {
... Application methods ...
... WrapperListener methods...
public static void main(String[] args) {
// Start the application. If the JVM was launched from the native
// Wrapper then the application will wait for the native Wrapper to
// call the application's start method. Otherwise the start method
// will be called immediately.
WrapperManager.start(new MyApp(), args);
}
}
|
|
API Available to Your Application |
It is often necessary for your application to control its own lifecycle
as a service. This includes requesting that your application be stopped
or restarted.
The Java Service Wrapper allows your application access to the Wrapper
via the WrapperManager class.
Please see the JavaDocs for details.
|
|
|  |