|
| |
|
| java.lang.Object
 org.tanukisoftware.wrapper.WrapperManager
| WrapperManager | | final public class WrapperManager implements Runnable(Code) | | Handles all communication with the native portion of the Wrapper code.
The native wrapper code will launch Java in a separate process and set
up a server socket which the Java code is expected to open a socket to
on startup. When the server socket is created, a port will be chosen
depending on what is available to the system. This port will then be
passed to the Java process as property named "wrapper.port".
For security reasons, the native code will only allow connections from
localhost and will expect to receive the key specified in a property
named "wrapper.key".
This class is implemented as a singleton class.
Generate JNI Headers with the following command in the build/classes
directory:
javah -jni -classpath ./ org.tanukisoftware.wrapper.WrapperManager
author:
Leif Mortenson |
| Method Summary | |
| public static void | accessViolation()
(Testing Method) Cause an access violation within the Java code. | | public static void | accessViolationNative()
(Testing Method) Cause an access violation within native JNI code. | | public static void | addWrapperEventListener(WrapperEventListener listener, long mask)
Adds a WrapperEventListener which will receive WrapperEvents. | | public static void | appearHung()
(Testing Method) Causes the WrapperManager to go into a state which makes the JVM appear
to be hung when viewed from the native Wrapper code. | | public static String | getBuildTime()
Obtain the build time of Wrapper. | | public static WrapperUser | getInteractiveUser(boolean groups)
Returns a WrapperUser object which describes the interactive user whose
desktop is being interacted with. | | public static int | getJVMId()
Returns the Id of the current JVM. | | public static int | getJavaPID()
Returns the PID of the Java process. | | public static Properties | getProperties()
Returns a Properties object containing expanded the contents of the
configuration file used to launch the Wrapper. | | public static WrapperUser | getUser(boolean groups)
Returns a WrapperUser object which describes the user under which the
Wrapper is currently running. | | public static String | getVersion()
Obtain the current version of Wrapper. | | public static int | getWrapperPID()
Returns the PID of the Wrapper process. | | public static boolean | hasShutdownHookBeenTriggered()
Returns true if the ShutdownHook for the JVM has already been triggered. | | public static boolean | isControlledByNativeWrapper()
Returns true if the JVM was launched by the Wrapper application. | | public static boolean | isDebugEnabled()
Returns true if the wrapper.debug property, or any of the logging
channels are set to DEBUG in the wrapper configuration file. | | public static boolean | isLaunchedAsService()
Returns true if the Wrapper was launched as an NT service on Windows or
as a daemon process on UNIX platforms. | | public static WrapperWin32Service[] | listServices()
Returns an array of all registered services. | | public static void | log(int logLevel, String message)
Requests that the Wrapper log a message at the specified log level.
If the JVM is not being managed by the Wrapper then calls to this
method will be ignored. | | public static void | removeWrapperEventListener(WrapperEventListener listener)
Removes a WrapperEventListener so it will not longer receive WrapperEvents. | | public static void | requestThreadDump()
Requests that the current JVM process request a thread dump. | | public static void | restart()
Tells the native wrapper that the JVM wants to restart, then informs
all listeners that the JVM is about to shutdown before killing the JVM. | | public static void | restartAndReturn()
Tells the native wrapper that the JVM wants to restart, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method requests that the JVM be restarted but then returns. | | public void | run()
| | public static WrapperWin32Service | sendServiceControlCode(String serviceName, int controlCode)
Sends a service control code to the specified service. | | public static void | setConsoleTitle(String title)
Sets the title of the console in which the Wrapper is running. | | public static void | signalStarting(int waitHint)
Signal the native wrapper that the startup is progressing but that more
time is needed. | | public static void | signalStopped(int exitCode)
This method should not normally be called by user code as it is called
from within the stop and restart methods. | | public static void | signalStopping(int waitHint)
Signal the native wrapper that the shutdown is progressing but that more
time is needed. | | public static synchronized void | start(WrapperListener listener, String[] args)
Start the Java side of the Wrapper code running. | | public static void | stop(int exitCode)
Tells the native wrapper that the JVM wants to shut down, then informs
all listeners that the JVM is about to shutdown before killing the JVM. | | public static void | stopAndReturn(int exitCode)
Tells the native wrapper that the JVM wants to shut down, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method requests that the JVM be shutdown but then returns. | | public static void | stopImmediate(int exitCode)
Tells the native wrapper that the JVM wants to shut down and then
promptly halts. |
| SERVICE_CONTROL_CODE_CONTINUE | | final public static int SERVICE_CONTROL_CODE_CONTINUE(Code) | | Service Control code which can be sent to resume a paused service.
|
| SERVICE_CONTROL_CODE_INTERROGATE | | final public static int SERVICE_CONTROL_CODE_INTERROGATE(Code) | | Service Control code which can be sent to or received interrogate the status of a service.
|
| SERVICE_CONTROL_CODE_PAUSE | | final public static int SERVICE_CONTROL_CODE_PAUSE(Code) | | Service Control code which can be sent to pause a service.
|
| SERVICE_CONTROL_CODE_SHUTDOWN | | final public static int SERVICE_CONTROL_CODE_SHUTDOWN(Code) | | Service Control code which can be received when the system is shutting down.
|
| SERVICE_CONTROL_CODE_START | | final public static int SERVICE_CONTROL_CODE_START(Code) | | Service Control code which can be sent to start a service.
|
| SERVICE_CONTROL_CODE_STOP | | final public static int SERVICE_CONTROL_CODE_STOP(Code) | | Service Control code which can be sent or received to stop a service.
|
| WRAPPER_CTRL_CLOSE_EVENT | | final public static int WRAPPER_CTRL_CLOSE_EVENT(Code) | | Received when the user clicks on the close button of a Console on Windows.
|
| WRAPPER_CTRL_C_EVENT | | final public static int WRAPPER_CTRL_C_EVENT(Code) | | Received when the user presses CTRL-C in the console on Windows or UNIX platforms.
|
| WRAPPER_CTRL_HUP_EVENT | | final public static int WRAPPER_CTRL_HUP_EVENT(Code) | | Received when a SIG HUP is received on a UNIX system.
|
| WRAPPER_CTRL_LOGOFF_EVENT | | final public static int WRAPPER_CTRL_LOGOFF_EVENT(Code) | | Received when the user logs off of a Windows system.
|
| WRAPPER_CTRL_SHUTDOWN_EVENT | | final public static int WRAPPER_CTRL_SHUTDOWN_EVENT(Code) | | Received when a Windows system is shutting down.
|
| WRAPPER_CTRL_TERM_EVENT | | final public static int WRAPPER_CTRL_TERM_EVENT(Code) | | Received when a SIG TERM is received on a UNIX system.
|
| WRAPPER_LOG_LEVEL_ADVICE | | final public static int WRAPPER_LOG_LEVEL_ADVICE(Code) | | Log message at advice log level.
|
| WRAPPER_LOG_LEVEL_DEBUG | | final public static int WRAPPER_LOG_LEVEL_DEBUG(Code) | | Log message at debug log level.
|
| WRAPPER_LOG_LEVEL_ERROR | | final public static int WRAPPER_LOG_LEVEL_ERROR(Code) | | Log message at error log level.
|
| WRAPPER_LOG_LEVEL_FATAL | | final public static int WRAPPER_LOG_LEVEL_FATAL(Code) | | Log message at fatal log level.
|
| WRAPPER_LOG_LEVEL_INFO | | final public static int WRAPPER_LOG_LEVEL_INFO(Code) | | Log message at info log level.
|
| WRAPPER_LOG_LEVEL_STATUS | | final public static int WRAPPER_LOG_LEVEL_STATUS(Code) | | Log message at status log level.
|
| WRAPPER_LOG_LEVEL_WARN | | final public static int WRAPPER_LOG_LEVEL_WARN(Code) | | Log message at warn log level.
|
| accessViolation | | public static void accessViolation()(Code) | | (Testing Method) Cause an access violation within the Java code. Useful
for testing the Wrapper functions. This currently only crashes Sun
JVMs and takes advantage of Bug #4369043 which does not exist in newer
JVMs. Use of the accessViolationNative() method is preferred.
|
| accessViolationNative | | public static void accessViolationNative()(Code) | | (Testing Method) Cause an access violation within native JNI code. Useful for testing the
Wrapper functions. This currently causes the access violation by attempting to write to
a null pointer.
|
| addWrapperEventListener | | public static void addWrapperEventListener(WrapperEventListener listener, long mask)(Code) | | Adds a WrapperEventListener which will receive WrapperEvents. The
specific events can be controlled using the mask parameter. This API
was chosen to allow for additional events in the future.
To avoid future compatibility problems, WrapperEventListeners should
always test the class of an event before making use of it. This will
avoid problems caused by new event classes added in future versions
of the Wrapper.
This method should only be called once for a given WrapperEventListener.
Build up a single mask to receive events of multiple types.
Parameters:
listener - WrapperEventListener to be start receiving events.
Parameters:
mask - A mask specifying the event types that the listener isinterrested in receiving. See the WrapperEventListenerclass for a full list of flags. A mask is created bycombining multiple flags using the binary '|' OR operator. |
| appearHung | | public static void appearHung()(Code) | | (Testing Method) Causes the WrapperManager to go into a state which makes the JVM appear
to be hung when viewed from the native Wrapper code. Does not have any effect when the
JVM is not being controlled from the native Wrapper. Useful for testing the Wrapper
functions.
|
| getBuildTime | | public static String getBuildTime()(Code) | | Obtain the build time of Wrapper.
The time that the Wrapper was built. |
| getInteractiveUser | | public static WrapperUser getInteractiveUser(boolean groups)(Code) | | Returns a WrapperUser object which describes the interactive user whose
desktop is being interacted with. When a service running on a Windows
platform has its interactive flag set, this method will return the user
who is currently logged in. Additional platform specific information
can be obtained by casting the object to a platform specific subclass.
WrapperWin32User, for example.
If a user is not currently logged on then this method will return null.
User code can repeatedly call this method to detect when a user has
logged in. To detect when a user has logged out, there are two options.
1) The user code can continue to call this method until it returns null.
2) Or if the WrapperListener method is being implemented, the
WrapperListener.controlEvent method will receive a WRAPPER_CTRL_LOGOFF_EVENT
event when the user logs out.
On XP systems, it is possible to switch to another account rather than
actually logging out. In such a case, the interactive user will be
the first user that logged in. This will also be the only user with
which the service will interact. If other users are logged in when the
interactive user logs out, the service will not automatically switch to
another logged in user. Rather, the next user to log in will become
the new user which the service will interact with.
This method will always return NULL on versions of NT prior to Windows
2000. This can not be helped as some required functions were not added
to the windows API until NT version 5.0, also known as Windows 2000.
Parameters:
groups - True if the user's groups should be returned as well.Requesting the groups that a user belongs to increasesthe CPU load required to complete the call. The current interactive user, or null. |
| getJVMId | | public static int getJVMId()(Code) | | Returns the Id of the current JVM. JVM Ids increment from 1 each time
the wrapper restarts a new one.
The Id of the current JVM. |
| getJavaPID | | public static int getJavaPID()(Code) | | Returns the PID of the Java process.
A PID of 0 will be returned if the native library has not been initialized.
This value can also be obtained using the 'wrapper.java.pid' system property.
The PID of the Java process. |
| getProperties | | public static Properties getProperties()(Code) | | Returns a Properties object containing expanded the contents of the
configuration file used to launch the Wrapper.
All properties are included so it is possible to define properties
not used by the Wrapper in the configuration file and have then
be available in this Properties object.
The contents of the Wrapper configuration file. |
| getUser | | public static WrapperUser getUser(boolean groups)(Code) | | Returns a WrapperUser object which describes the user under which the
Wrapper is currently running. Additional platform specific information
can be obtained by casting the object to a platform specific subclass.
WrapperWin32User, for example.
Parameters:
groups - True if the user's groups should be returned as well.Requesting the groups that a user belongs to increasesthe CPU load required to complete the call. An object describing the current user. |
| getVersion | | public static String getVersion()(Code) | | Obtain the current version of Wrapper.
The version of the Wrapper. |
| getWrapperPID | | public static int getWrapperPID()(Code) | | Returns the PID of the Wrapper process.
A PID of 0 will be returned if the JVM was launched standalone.
This value can also be obtained using the 'wrapper.pid' system property.
The PID of the Wrpper process. |
| hasShutdownHookBeenTriggered | | public static boolean hasShutdownHookBeenTriggered()(Code) | | Returns true if the ShutdownHook for the JVM has already been triggered.
Some code needs to know whether or not the system is shutting down.
True if the ShutdownHook for the JVM has already been triggered. |
| isControlledByNativeWrapper | | public static boolean isControlledByNativeWrapper()(Code) | | Returns true if the JVM was launched by the Wrapper application. False
if the JVM was launched manually without the Wrapper controlling it.
True if the current JVM was launched by the Wrapper. |
| isDebugEnabled | | public static boolean isDebugEnabled()(Code) | | Returns true if the wrapper.debug property, or any of the logging
channels are set to DEBUG in the wrapper configuration file. Useful
for deciding whether or not to output certain information to the
console.
True if the Wrapper is logging any Debug level output. |
| isLaunchedAsService | | public static boolean isLaunchedAsService()(Code) | | Returns true if the Wrapper was launched as an NT service on Windows or
as a daemon process on UNIX platforms. False if launched as a console.
This can be useful if you wish to display a user interface when in
Console mode. On UNIX platforms, this is not as useful because an
X display may not be visible even if launched in a console.
True if the Wrapper is running as an NT service or daemonprocess. |
| listServices | | public static WrapperWin32Service[] listServices() throws SecurityException(Code) | | Returns an array of all registered services. This method is only
supported on Windows platforms which support services. Calling this
method on other platforms will result in null being returned.
An array of services.
throws:
SecurityException - If a SecurityManager has not been set in theJVM or if the calling code has not beengranted the WrapperPermission "listServices"permission. A SecurityManager is requiredfor this operation because this method makesit possible to learn a great deal about thestate of the system. |
| log | | public static void log(int logLevel, String message)(Code) | | Requests that the Wrapper log a message at the specified log level.
If the JVM is not being managed by the Wrapper then calls to this
method will be ignored. This method has been optimized to ignore
messages at a log level which will not be logged given the current
log levels of the Wrapper.
Log messages will currently by trimmed by the Wrapper at 4k (4096 bytes).
Because of differences in the way console output is collected and
messages logged via this method, it is expected that interspersed
console and log messages will not be in the correct order in the
resulting log file.
This method was added to allow simple logging to the wrapper.log
file. This is not meant to be a full featured log file and should
not be used as such. Please look into a logging package for most
application logging.
Parameters:
logLevel - The level to log the message at can be one ofWRAPPER_LOG_LEVEL_DEBUG, WRAPPER_LOG_LEVEL_INFO,WRAPPER_LOG_LEVEL_STATUS, WRAPPER_LOG_LEVEL_WARN,WRAPPER_LOG_LEVEL_ERROR, or WRAPPER_LOG_LEVEL_FATAL.
Parameters:
message - The message to be logged.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("log") permission.
See Also: WrapperPermission |
| removeWrapperEventListener | | public static void removeWrapperEventListener(WrapperEventListener listener)(Code) | | Removes a WrapperEventListener so it will not longer receive WrapperEvents.
Parameters:
listener - WrapperEventListener to be stop receiving events. |
| requestThreadDump | | public static void requestThreadDump()(Code) | | Requests that the current JVM process request a thread dump. This is
the same as pressing CTRL-BREAK (under Windows) or CTRL-\ (under Unix)
in the the console in which Java is running. This method does nothing
if the native library is not loaded.
|
| restart | | public static void restart() throws SecurityException(Code) | | Tells the native wrapper that the JVM wants to restart, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method will not return.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("restart") permission.
See Also: WrapperPermission |
| restartAndReturn | | public static void restartAndReturn() throws SecurityException(Code) | | Tells the native wrapper that the JVM wants to restart, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method requests that the JVM be restarted but then returns. This
allows components to initiate a JVM exit and then continue, allowing
a normal shutdown initiated by the JVM via shutdown hooks. In
applications which are designed to be shutdown when the user presses
CTRL-C, this may result in a cleaner shutdown.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("restart") permission.
See Also: WrapperPermission |
| sendServiceControlCode | | public static WrapperWin32Service sendServiceControlCode(String serviceName, int controlCode) throws WrapperServiceException, SecurityException(Code) | | Sends a service control code to the specified service. The state of the
service should be tested on return. If the service was not currently
running then the control code will not be sent.
The control code sent can be one of the system control codes:
WrapperManager.SERVICE_CONTROL_CODE_START,
WrapperManager.SERVICE_CONTROL_CODE_STOP,
WrapperManager.SERVICE_CONTROL_CODE_PAUSE,
WrapperManager.SERVICE_CONTROL_CODE_CONTINUE, or
WrapperManager.SERVICE_CONTROL_CODE_INTERROGATE. In addition, user
defined codes in the range 128-255 can also be sent.
Parameters:
serviceName - Name of the Windows service which will receive thecontrol code.
Parameters:
controlCode - The actual control code to be sent. User definedcontrol codes should be in the range 128-255. A WrapperWin32Service containing the last known status of theservice after sending the control code. This will be null ifthe currently platform is not a version of Windows whichsupports services.
throws:
WrapperServiceException - If there are any problems accessing thespecified service.
throws:
SecurityException - If a SecurityManager has not been set in theJVM or if the calling code has not beengranted the WrapperServicePermissionpermission for the specified service andcontrol code. A SecurityManager is requiredfor this operation because this method makesit possible to control any service on thesystem, which is of course rather dangerous. |
| setConsoleTitle | | public static void setConsoleTitle(String title)(Code) | | Sets the title of the console in which the Wrapper is running. This
is currently only supported on Windows platforms.
As an alternative, it is also possible to set the console title from
within the wrapper.conf file using the wrapper.console.title property.
Parameters:
title - The new title. The specified string will be encodedto a byte array using the default encoding for thecurrent platform. |
| signalStarting | | public static void signalStarting(int waitHint)(Code) | | Signal the native wrapper that the startup is progressing but that more
time is needed. The Wrapper will extend the startup timeout by the
specified time.
Parameters:
waitHint - Additional time in milliseconds.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("signalStarting") permission.
See Also: WrapperPermission |
| signalStopped | | public static void signalStopped(int exitCode)(Code) | | This method should not normally be called by user code as it is called
from within the stop and restart methods. However certain applications
which stop the JVM may need to call this method to let the wrapper code
know that the shutdown was intentional.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("signalStopped") permission.
See Also: WrapperPermission |
| signalStopping | | public static void signalStopping(int waitHint)(Code) | | Signal the native wrapper that the shutdown is progressing but that more
time is needed. The Wrapper will extend the stop timeout by the
specified time.
Parameters:
waitHint - Additional time in milliseconds.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("signalStopping") permission.
See Also: WrapperPermission |
| start | | public static synchronized void start(WrapperListener listener, String[] args)(Code) | | Start the Java side of the Wrapper code running. This will make it
possible for the native side of the Wrapper to detect that the Java
Wrapper is up and running.
This method must be called on startup and then can only be called once
so there is no reason for any security permission checks on this call.
Parameters:
listener - The WrapperListener instance which represents theapplication being started.
Parameters:
args - The argument list passed to the JVM when it was launched. |
| stop | | public static void stop(int exitCode)(Code) | | Tells the native wrapper that the JVM wants to shut down, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method will not return.
Parameters:
exitCode - The exit code that the Wrapper will return when it exits.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("stop") permission.
See Also: WrapperPermission |
| stopAndReturn | | public static void stopAndReturn(int exitCode)(Code) | | Tells the native wrapper that the JVM wants to shut down, then informs
all listeners that the JVM is about to shutdown before killing the JVM.
This method requests that the JVM be shutdown but then returns. This
allows components to initiate a JVM exit and then continue, allowing
a normal shutdown initiated by the JVM via shutdown hooks. In
applications which are designed to be shutdown when the user presses
CTRL-C, this may result in a cleaner shutdown.
Parameters:
exitCode - The exit code that the Wrapper will return when it exits.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("stop") permission.
See Also: WrapperPermission |
| stopImmediate | | public static void stopImmediate(int exitCode)(Code) | | Tells the native wrapper that the JVM wants to shut down and then
promptly halts. Be careful when using this method as an application
will not be given a chance to shutdown cleanly.
Parameters:
exitCode - The exit code that the Wrapper will return when it exits.
throws:
SecurityException - If a SecurityManager is present and thecalling thread does not have theWrapperPermission("stopImmediate") permission.
See Also: WrapperPermission |
|
|
|