org.tanukisoftware.wrapper

Class WrapperProcessConfig

java.lang.Object

org.tanukisoftware.wrapper.WrapperProcessConfig

public final class WrapperProcessConfig
extends java.lang.Object

With WrapperProcessConfig Class the startup configuration for the Process can be passed to the WrapperManager.exec methods. The configuration makes it possible to control the way the OS spawns the child process, specify environment variables, working directory, and how the Wrapper should handle process when the JVM exits. Please review each of the methods a more detailed explanation of how they work.

The setter methods are designed to be optionally be chained as follows:

 WrapperProcess proc = WrapperManager.exec( "command", new WrapperProcessConfig().setDetached( true ).setStartType( WrapperProcessConfig.POSIX_SPAWN ) );
 

Since:

Wrapper 3.4.0

Author:

Tanuki Software Development Team <support@tanukisoftware.com>

Field Summary

Fields

Modifier and Type	Field and Description
static int	DYNAMIC
static int	FORK_EXEC
static int	POSIX_SPAWN
static int	VFORK_EXEC

Constructor Summary

Constructors

Constructor and Description
WrapperProcessConfig() Creates a default configuration.

Method Summary

Modifier and Type	Method and Description
java.util.Map	getEnvironment() Returns a Map containing the environment which will be used to launch the child process.
int	getSoftShutdownTimeout() Returns the soft shutdown timeout value.
int	getStartType() Returns the start type.
java.io.File	getWorkingDirectory() Returns the working directory.
boolean	isAutoCloseInputStreams() Returns whether the input streams of the process should be read in 'auto-close' mode.
boolean	isCreateForActiveUser() Tells if the CreateForActiveUser feature was enabled.
boolean	isDetached() Returns the detached flag.
boolean	isNewProcessGroup() Returns the new process group flag.
static boolean	isSupported(int startType) Indicates whether the specified start type is supported on the current plattform.
WrapperProcessConfig	setAutoCloseInputStreams(boolean isAutoCloseInputStreams) Specifies how the pipes of the process should be read.
WrapperProcessConfig	setCreateForActiveUser(boolean isInteractive) Specifies if the ChildProcesses should be launched in the current session.
WrapperProcessConfig	setDetached(boolean detached) Sets the detached flag.
WrapperProcessConfig	setEnvironment(java.util.Map environment) Sets the environment for the child process.
WrapperProcessConfig	setNewProcessGroup(boolean newProcessGroup) Sets the new process group flag.
WrapperProcessConfig	setSoftShutdownTimeout(int softShutdownTimeout) Sets the timeout for the soft shtudown in seconds.
WrapperProcessConfig	setStartType(int startType) Sets the start type.
WrapperProcessConfig	setWorkingDirectory(java.io.File workingDirectory) Sets the working directory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POSIX_SPAWN

public static final int POSIX_SPAWN

See Also:

Constant Field Values

FORK_EXEC

public static final int FORK_EXEC

See Also:

Constant Field Values

VFORK_EXEC

public static final int VFORK_EXEC

See Also:

Constant Field Values

DYNAMIC

public static final int DYNAMIC

See Also:

Constant Field Values

Constructor Detail

WrapperProcessConfig

public WrapperProcessConfig()

Creates a default configuration.

Throws:

WrapperLicenseError - If the function is called other than in the Professional Edition or if the native library has not been loaded.

Method Detail

isSupported

public static boolean isSupported(int startType)
                           throws WrapperLicenseError,
                                  java.lang.IllegalArgumentException

Indicates whether the specified start type is supported on the current plattform.

Parameters:

startType - The start type to test.

Returns:

true if supported, false otherwise. On Windows, this method always returns true.

Throws:

WrapperLicenseError - If the function is called other than in the Professional Edition or if the native library has not been loaded.

java.lang.IllegalArgumentException - If the startType is invalid.

isDetached

public boolean isDetached()

Returns the detached flag.

Returns:

The detached flag.

setDetached

public WrapperProcessConfig setDetached(boolean detached)

Sets the detached flag. This makes it possible to control whether or not the Wrapper will terminate any child processes launched by a JVM when that JVM exits or crashes. Note that when running the Wrapper as daemon with systemd, systemd may kill all child processes (including detached ones) on shutdown. To prevent this, please adjust the value of the SYSTEMD_KILLMODE property in the Wrapper Shell script.

Parameters:

detached - If false the Wrapper will remember that the process was launched and then make sure that it is terminated when the JVM exits.

Returns:

This configration to allow chaining.

getStartType

public int getStartType()

Returns the start type.

Returns:

The start type.

setStartType

public WrapperProcessConfig setStartType(int startType)
                                  throws java.lang.IllegalArgumentException

Sets the start type.

The start type is used to control how the subprocess will be started by the OS. This property has no effect on Windows.

• FORK_EXEC - The most common UNIX/LINUX way to create a child process. On some operating systems (esp. Solaris) this call causes results in the operating system momentarily duplicating the JVM's memory before launching the child process. If the JVM is large then this can result in system level memory errors that can cause the child process to fail or even the JVM to crash.
• VFORK_EXEC - The vfork function differs from fork only in that the child process can share code and data with the parent process. This speeds cloning activity significantly. Care is taken in this implementation to avoid the kind of integrety problems that are possible with this method. On some systems, vfork is the same as fork.
• POSIX_SPAWN - The process will be spawned in such a way that no memory duplication takes place. This makes it possible to spawn child processes when the JVM is very large on Solaris systems. (See http://www.opengroup.org/onlinepubs/009695399/functions/posix_spawn.html) This is available on LINUX, SOLARIS (10+), AIX, z/OS and MACOS. It will not be possible to set the working directory when using this start type.
• DYNAMIC - The ideal forking method will be used for the current platform. It will not be possible to set the working directory when using this start type as the start type used on some platforms does not support setting a working directory.

Parameters:

startType - The start type to use when launching the child process.

Returns:

This configration to allow chaining.

Throws:

java.lang.IllegalArgumentException - If the startType is invalid.

isNewProcessGroup

public boolean isNewProcessGroup()

Returns the new process group flag.

Returns:

The new process group flag.

setNewProcessGroup

public WrapperProcessConfig setNewProcessGroup(boolean newProcessGroup)

Sets the new process group flag.

When a process is created as a new process group, the Wrapper will monitor and terminate all processes in the new process group.

When false, the process will be a member of the same process group as Java. The Wrapper will only monitor the process which was directly launched.

Defaults to true.

On Windows, this value is ignored. A new process group is required to make sure console events are handled correctly.

Parameters:

newProcessGroup - True to create a new process group, false to inherit the process group.

Returns:

This configration to allow chaining.

isAutoCloseInputStreams

public boolean isAutoCloseInputStreams()

Returns whether the input streams of the process should be read in 'auto-close' mode.

Returns:

true if non-blocking mode is enabled, FALSE otherwise.

setAutoCloseInputStreams

public WrapperProcessConfig setAutoCloseInputStreams(boolean isAutoCloseInputStreams)

Specifies how the pipes of the process should be read.

Two modes are possible:

With the 'auto-close' mode, which is the default, the input stream will be closed when the process ends and there is nothing else to read from the std[out/err] to which it is connected.

In the other mode, the input stream will wait for data to be read even if the process is gone as long as the other end of the stream is open.

While the second mode might be slightly more efficient during the process of reading data, it can cause to block longer after the process termination in case other sub-processes using the same standard streams were initiated. These sub-processes may indeed force the standard streams to stay open.

The 'auto-close' mode is also more reliable in the event of the process crashing.

Defaults to true.

On z/OS, this value is ignored. The 'auto-close' mode is required to make sure the pipes are read correctly. On Windows, this value is ignored. The 'auto-close' mode is not needed.

Parameters:

isAutoCloseInputStreams - true to enable 'auto-close' mode, false to disable it.

Returns:

This configration to allow chaining.

getWorkingDirectory

public java.io.File getWorkingDirectory()

Returns the working directory.

Returns:

The working directory.

setWorkingDirectory

public WrapperProcessConfig setWorkingDirectory(java.io.File workingDirectory)
                                         throws java.io.IOException

Sets the working directory.

Parameters:

workingDirectory - The working directory of the subprocess, or null if the subprocess should inherit the working directory of the JVM. On Unix, when using the POSIX_SPAWN or DYNAMIC start type, it is not possible to set the working directory. Doing so will result in an error when running exec. On Windows, it is always possible to set the working directly.

Returns:

This configration to allow chaining.

Throws:

java.io.IOException - If the specified working directory can not be resolved.

getEnvironment

public java.util.Map getEnvironment()
                             throws WrapperLicenseError

Returns a Map containing the environment which will be used to launch the child process.

If this Map is modified those changes will be reflected when the process is launched. Alternately, the environment can be set with the setEnvironment method. Clearing the Map will result in an empty environment being used.

Returns:

A Map containing the environment which will be used to launch the child process.

Throws:

WrapperLicenseError - If the function is called other than in the Professional Edition or from a Standalone JVM.

setEnvironment

public WrapperProcessConfig setEnvironment(java.util.Map environment)

Sets the environment for the child process.

Parameters:

environment - A Map containing the environment to use when launching the process. Passing in an empty Map will result in an empty Environment being used. A null native will cause the process to be launched using the same environment as the JVM.

Returns:

This configration to allow chaining.

Throws:

java.lang.IllegalArgumentException - If any of the names or values are not Strings or if a name is empty.

getSoftShutdownTimeout

public int getSoftShutdownTimeout()

Returns the soft shutdown timeout value.

Returns:

The soft shutdown timeout value.

setSoftShutdownTimeout

public WrapperProcessConfig setSoftShutdownTimeout(int softShutdownTimeout)

Sets the timeout for the soft shtudown in seconds. When WrapperProcess.destroy() is called the wrapper will first try to stop the application softly giving it time to stop itself properly. If the specified timeout however ellapsed, the Child Process will be terminated by hard. If 0 was specified, the wrapper will instantly force the termination. If -1 was specified, the wrapper will wait indefinitely for the child to perform the stop. The default value of this property is 5 - giving a process 5 sec to react on the shutdown request. On Windows, Window based applications will be asked to shutdown by sending WM_CLOSE messages to each of their Window event queues. The soft shutdown will be ignored for console processes as it is not currently possible to ask them to shutdown cleanly with a CTRL-C.

Parameters:

softShutdownTimeout - The max timeout for an application to stop, before killing forcibly

Returns:

This configration to allow chaining.

Throws:

java.lang.IllegalArgumentException - If the value of the specified timeout is invalid.

setCreateForActiveUser

public WrapperProcessConfig setCreateForActiveUser(boolean isInteractive)

Specifies if the ChildProcesses should be launched in the current session. This property only makes sense if the application was launched as Windows Service under the System User (or any other user, having SE_TCB_NAME previledge with the OS) On non-Windows platforms or when launched in Console mode, the setting will be ignored silently.

Parameters:

isInteractive - true to enable the feature.

Returns:

An instance of WrapperProcessConfig.

isCreateForActiveUser

public boolean isCreateForActiveUser()

Tells if the CreateForActiveUser feature was enabled.

Returns:

CreateForActiveUser.