public final class WrapperManager
extends java.lang.Object
implements java.lang.Runnable
Modifier and Type | Field and Description |
---|---|
static int |
SERVICE_CONTROL_CODE_CONTINUE
Service Control code which can be sent to resume a paused service.
|
static int |
SERVICE_CONTROL_CODE_INTERROGATE
Service Control code which can be sent to or received interrogate the status of a service.
|
static int |
SERVICE_CONTROL_CODE_PAUSE
Service Control code which can be sent to pause a service.
|
static int |
SERVICE_CONTROL_CODE_SHUTDOWN
Service Control code which can be received when the system is shutting down.
|
static int |
SERVICE_CONTROL_CODE_START
Service Control code which can be sent to start a service.
|
static int |
SERVICE_CONTROL_CODE_STOP
Service Control code which can be sent or received to stop a service.
|
static int |
WRAPPER_CTRL_C_EVENT
Received when the user presses CTRL-C in the console on Windows or UNIX platforms.
|
static int |
WRAPPER_CTRL_CLOSE_EVENT
Received when the user clicks on the close button of a Console on Windows.
|
static int |
WRAPPER_CTRL_HUP_EVENT
Received when a SIG HUP is received on a UNIX system.
|
static int |
WRAPPER_CTRL_LOGOFF_EVENT
Received when the user logs off of a Windows system.
|
static int |
WRAPPER_CTRL_SHUTDOWN_EVENT
Received when a Windows system is shutting down.
|
static int |
WRAPPER_CTRL_TERM_EVENT
Received when a SIG TERM is received on a UNIX system.
|
static int |
WRAPPER_CTRL_USR1_EVENT
Received when a SIG USR1 is received on a UNIX system.
|
static int |
WRAPPER_CTRL_USR2_EVENT
Received when a SIG USR2 is received on a UNIX system.
|
static int |
WRAPPER_LOG_LEVEL_ADVICE
Log message at advice log level.
|
static int |
WRAPPER_LOG_LEVEL_DEBUG
Log message at debug log level.
|
static int |
WRAPPER_LOG_LEVEL_ERROR
Log message at error log level.
|
static int |
WRAPPER_LOG_LEVEL_FATAL
Log message at fatal log level.
|
static int |
WRAPPER_LOG_LEVEL_INFO
Log message at info log level.
|
static int |
WRAPPER_LOG_LEVEL_STATUS
Log message at status log level.
|
static int |
WRAPPER_LOG_LEVEL_WARN
Log message at warn log level.
|
Modifier and Type | Method and Description |
---|---|
static void |
accessViolation()
(Testing Method) Cause an access violation within the Java code.
|
static void |
accessViolationNative()
(Testing Method) Cause an access violation within native JNI code.
|
static void |
addWrapperEventListener(WrapperEventListener listener,
long mask)
Adds a WrapperEventListener which will receive WrapperEvents.
|
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.
|
static java.lang.String |
getBuildTime()
Obtain the build time of Wrapper.
|
static WrapperUser |
getInteractiveUser(boolean groups)
Returns a WrapperUser object which describes the interactive user whose
desktop is being interacted with.
|
static int |
getJavaPID()
Returns the PID of the Java process.
|
static int |
getJVMId()
Returns the Id of the current JVM.
|
static java.util.Properties |
getProperties()
Returns a Properties object containing expanded the contents of the
configuration file used to launch the Wrapper.
|
static WrapperUser |
getUser(boolean groups)
Returns a WrapperUser object which describes the user under which the
Wrapper is currently running.
|
static java.lang.String |
getVersion()
Obtain the current version of Wrapper.
|
static int |
getWrapperPID()
Returns the PID of the Wrapper process.
|
static boolean |
hasShutdownHookBeenTriggered()
Returns true if the ShutdownHook for the JVM has already been triggered.
|
static boolean |
isControlledByNativeWrapper()
Returns true if the JVM was launched by the Wrapper application.
|
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.
|
static boolean |
isLaunchedAsService()
Returns true if the Wrapper was launched as an NT service on Windows or
as a daemon process on UNIX platforms.
|
static boolean |
isProfessionalEdition()
Returns true if the current Wrapper edition has support for Professional
Edition features.
|
static boolean |
isStandardEdition()
Returns true if the current Wrapper edition has support for Standard
Edition features.
|
static WrapperWin32Service[] |
listServices()
Returns an array of all registered services.
|
static void |
log(int logLevel,
java.lang.String message)
Requests that the Wrapper log a message at the specified log level.
|
static void |
removeWrapperEventListener(WrapperEventListener listener)
Removes a WrapperEventListener so it will not longer receive WrapperEvents.
|
static void |
requestThreadDump()
Requests that the current JVM process request a thread dump.
|
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.
|
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.
|
void |
run() |
static WrapperWin32Service |
sendServiceControlCode(java.lang.String serviceName,
int controlCode)
Sends a service control code to the specified service.
|
static void |
setConsoleTitle(java.lang.String title)
Sets the title of the console in which the Wrapper is running.
|
static void |
signalStarting(int waitHint)
Signal the native wrapper that the startup is progressing but that more
time is needed.
|
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.
|
static void |
signalStopping(int waitHint)
Signal the native wrapper that the shutdown is progressing but that more
time is needed.
|
static void |
start(WrapperListener listener,
java.lang.String[] args)
Start the Java side of the Wrapper code running.
|
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.
|
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.
|
static void |
stopImmediate(int exitCode)
Tells the native wrapper that the JVM wants to shut down and then
promptly halts.
|
public static final int WRAPPER_CTRL_C_EVENT
public static final int WRAPPER_CTRL_CLOSE_EVENT
public static final int WRAPPER_CTRL_LOGOFF_EVENT
public static final int WRAPPER_CTRL_SHUTDOWN_EVENT
public static final int WRAPPER_CTRL_TERM_EVENT
public static final int WRAPPER_CTRL_HUP_EVENT
public static final int WRAPPER_CTRL_USR1_EVENT
public static final int WRAPPER_CTRL_USR2_EVENT
public static final int WRAPPER_LOG_LEVEL_DEBUG
public static final int WRAPPER_LOG_LEVEL_INFO
public static final int WRAPPER_LOG_LEVEL_STATUS
public static final int WRAPPER_LOG_LEVEL_WARN
public static final int WRAPPER_LOG_LEVEL_ERROR
public static final int WRAPPER_LOG_LEVEL_FATAL
public static final int WRAPPER_LOG_LEVEL_ADVICE
public static final int SERVICE_CONTROL_CODE_START
public static final int SERVICE_CONTROL_CODE_STOP
public static final int SERVICE_CONTROL_CODE_PAUSE
public static final int SERVICE_CONTROL_CODE_CONTINUE
public static final int SERVICE_CONTROL_CODE_INTERROGATE
public static final int SERVICE_CONTROL_CODE_SHUTDOWN
public static java.lang.String getVersion()
public static java.lang.String getBuildTime()
public static int getJVMId()
public static boolean isProfessionalEdition()
public static boolean isStandardEdition()
public static void setConsoleTitle(java.lang.String title)
As an alternative, it is also possible to set the console title from within the wrapper.conf file using the wrapper.console.title property.
title
- The new title. The specified string will be encoded
to a byte array using the default encoding for the
current platform.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("setConsoleTitle")
permission.WrapperPermission
public static WrapperUser getUser(boolean groups)
groups
- True if the user's groups should be returned as well.
Requesting the groups that a user belongs to increases
the CPU load required to complete the call.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("getUser") permission.WrapperPermission
public static WrapperUser getInteractiveUser(boolean groups)
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.
groups
- True if the user's groups should be returned as well.
Requesting the groups that a user belongs to increases
the CPU load required to complete the call.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("getInteractiveUser")
permission.WrapperPermission
public static java.util.Properties getProperties()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("getProperties")
permission.WrapperPermission
public static int getWrapperPID()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("getWrapperPID") permission.WrapperPermission
public static int getJavaPID()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("getJavaPID") permission.WrapperPermission
public static void requestThreadDump()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("requestThreadDump")
permission.WrapperPermission
public static void appearHung()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("test.appearHung") permission.WrapperPermission
public static void accessViolation()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("test.accessViolation")
permission.WrapperPermission
public static void accessViolationNative()
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("test.accessViolationNative")
permission.WrapperPermission
public static boolean isControlledByNativeWrapper()
public static boolean isLaunchedAsService()
public static boolean isDebugEnabled()
public static void start(WrapperListener listener, java.lang.String[] args)
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.
listener
- The WrapperListener instance which represents the
application being started.args
- The argument list passed to the JVM when it was launched.public static void restart() throws java.lang.SecurityException
This method will not return.
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("restart") permission.WrapperPermission
public static void restartAndReturn() throws java.lang.SecurityException
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.
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("restart") permission.WrapperPermission
public static void stop(int exitCode)
This method will not return.
exitCode
- The exit code that the Wrapper will return when it exits.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("stop") permission.WrapperPermission
public static void stopAndReturn(int exitCode)
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.
exitCode
- The exit code that the Wrapper will return when it exits.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("stop") permission.WrapperPermission
public static void stopImmediate(int exitCode)
exitCode
- The exit code that the Wrapper will return when it exits.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("stopImmediate") permission.WrapperPermission
public static void signalStarting(int waitHint)
This call will have no effect if the current startup timeout is already more than 'waitHint' milliseconds in the future.
waitHint
- Time in milliseconds to allow for the startup to
complete.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("signalStarting") permission.WrapperPermission
public static void signalStopping(int waitHint)
This call will have no effect if the current shutdown timeout is already more than 'waitHint' milliseconds in the future.
waitHint
- Time in milliseconds to allow for the shutdown to
complete.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("signalStopping") permission.WrapperPermission
public static void signalStopped(int exitCode)
java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("signalStopped") permission.WrapperPermission
public static boolean hasShutdownHookBeenTriggered()
public static void log(int logLevel, java.lang.String message)
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.
logLevel
- The level to log the message at can be one of
WRAPPER_LOG_LEVEL_DEBUG, WRAPPER_LOG_LEVEL_INFO,
WRAPPER_LOG_LEVEL_STATUS, WRAPPER_LOG_LEVEL_WARN,
WRAPPER_LOG_LEVEL_ERROR, or WRAPPER_LOG_LEVEL_FATAL.message
- The message to be logged.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("log") permission.WrapperPermission
public static WrapperWin32Service[] listServices() throws java.lang.SecurityException
java.lang.SecurityException
- If a SecurityManager has not been set in the
JVM or if the calling code has not been
granted the WrapperPermission "listServices"
permission. A SecurityManager is required
for this operation because this method makes
it possible to learn a great deal about the
state of the system.WrapperPermission
public static WrapperWin32Service sendServiceControlCode(java.lang.String serviceName, int controlCode) throws WrapperServiceException, java.lang.SecurityException
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.
serviceName
- Name of the Windows service which will receive the
control code.controlCode
- The actual control code to be sent. User defined
control codes should be in the range 128-255.WrapperServiceException
- If there are any problems accessing the
specified service.java.lang.SecurityException
- If a SecurityManager has not been set in the
JVM or if the calling code has not been
granted the WrapperServicePermission
permission for the specified service and
control code. A SecurityManager is required
for this operation because this method makes
it possible to control any service on the
system, which is of course rather dangerous.WrapperServicePermission
public static void addWrapperEventListener(WrapperEventListener listener, long mask)
listener
- WrapperEventListener to be start receiving events.mask
- A mask specifying the event types that the listener is
interrested in receiving. See the WrapperEventListener
class for a full list of flags. A mask is created by
combining multiple flags using the binary '|' OR operator.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the appropriate
WrapperEventPermission(...) permission.WrapperEventPermission
public static void removeWrapperEventListener(WrapperEventListener listener)
listener
- WrapperEventListener to be stop receiving events.java.lang.SecurityException
- If a SecurityManager is present and the
calling thread does not have the
WrapperPermission("removeWrapperEventListener")
permission.WrapperPermission
public void run()
run
in interface java.lang.Runnable