Overview: Share Startup Properties

The wrapper.share<n>.startup.* properties basically define how the Wrapper will handle failures of mounted shares.

<n> component:

The "<n>" component of the property name is an integer number counting up from "1". By default, there can be no missing numbers. The wrapper.ignore_sequence_gaps property can optionally be set to allow gaps in the sequence.

wrapper.share.<n>.startup.failure

Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property defines the behaviour of the Wrapper if any general error occurred. Except for the premapped error (see below).

The user can specify that the Wrapper should:

  • SHUTDOWN itself if the Network Drive couldn't be mounted
  • BACKGROUND (Since ver. 3.5.52) its process and start the JVM, but continue trying to mount in the background
  • or CONTINUE its process and start the JVM, but stop trying to mount.

The default value is BACKGROUND.

Example:
wrapper.share.1.startup.failure=CONTINUE

NOTE

Prior to version 3.5.52, the default value was CONTINUE.

NOTE

An error "The network path was not found. (0x35)" can happen when the remote machine hosting the share is connected, but the requested mount point does not exist. However, the same error can also happen when the system is starting and is not yet ready for name resolution. It is not possible to distinguish between these 2 problems, so the Wrapper will treat this error as a temporary problem during startup, and as a permanent problem after it enters the second phase, which tries to mount the share in the background.

wrapper.share.<n>.startup.premapped

Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

WARNING

Prior to version 3.5.52, the default value was CONTINUE. The default was changed to SHUTDOWN. Please see details below.

This property specifies what the Wrapper will do if a share couldn't be mounted because the Network Resource already existed.

Please note that the behavior of the Wrapper for this error is not covered in the wrapper.share.<n>.startup.failure properties. This was made on purpose in order to provide a way to run the Wrapper as a console and as a service with the same configuration file.

Since version 3.5.52, if the target on the local machine already exists and is mapped to the same location as specified with wrapper.share.<n>.location, the Wrapper will consider the mounting done and continue regardless the value of wrapper.share.<n>.startup.premapped.

Conversely, if the target is the same, but the network location is different, chances are that the share was mapped to a different Network Resource (unless the location used an alias). In such cases, it is usually wiser to shut down, as this could lead to situations where the application might read or write at a wrong location. Along with this change, it was therefore decided to change the default value to SHUTDOWN.

The user can specify the Wrapper to either:

  • SHUTDOWN itself if the Network Drive already exists
  • or CONTINUE its process and start the JVM.

The default value is SHUTDOWN.

Example:
wrapper.share.1.startup.premapped=CONTINUE

wrapper.share.<n>.startup.max_retries

Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property defines how many times the Wrapper should try to mount a Network Drive if an network based error has occurred.

If the Wrapper couldn't mount the Network Drive at the maximum times of retries, the wrapper.share.<n>.startup.failure property will specify how the Wrapper will proceed.

The default value is "5 times". The Wrapper will try 5 times to mount a Network Drive before giving up.

Example: (5 times)
wrapper.share.1.startup.max_retries=5

wrapper.share.<n>.startup.retry_interval

Compatibility :3.5.0
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property specifies the interval in seconds the Wrapper will wait until it retries to mount a Network Drive.

The default value is "10 seconds". The Wrapper will wait for 10 seconds until it retries to mount.

Example: (10 seconds)
wrapper.share.1.startup.retry_interval=10

wrapper.share.<n>.background.retry_interval

Compatibility :3.5.52
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property specifies the interval in seconds that the Wrapper will wait until it retries to mount a Network Drive in the background after startup. This is the interval that the Wrapper will keep trying even after the application has started. It will keep trying until successfully mapped, or a permanent failure is detected.

Sometimes the server hosting the share is not reachable when the service starts. Continuing to try to mount in the background can be useful if the share is not critical to the application.

The default value is "60 seconds". The Wrapper will wait for 60 seconds until it retries to mount.

Example: (60 seconds)
wrapper.share.1.background.retry_interval=60

wrapper.share.<n>.background.success.action

Compatibility :3.5.52
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property allows to specify a certain action to be performed whenever a share is successfully mounted after application startup.

This can be useful to trigger a JVM restart, for example, when the application needs to reinitialize itself now that the share is available.

The default action is specified as NONE to do nothing.

Example:
wrapper.share.1.background.success.action=RESTART

The full list of actions can be viewed on this page, but the most commonly used are the following:

  • DEBUG:

    will cause a debug message to be logged. This is only really useful in helping to understand when the action is fired.

  • RESTART:

    will stop the current JVM and then restart a new invocation.

  • USER_<n> (Professional Edition):

    will cause a user defined event to be fired. This can be either the sending of an email, or the execution of an external system command. The command could be anything from performing clean up operations to raising an SNMP trap.

  • NONE:

    will do nothing (no further action once the share is successfully mounted).

wrapper.share.<n>.background.failure.action

Compatibility :3.5.52
Editions :Professional EditionStandard EditionCommunity Edition (Not Supported)
Platforms :WindowsMac OSX (Not Supported)Linux (Not Supported)IBM AIX (Not Supported)FreeBSD (Not Supported)HP-UX (Not Supported)Solaris (Not Supported)IBM z/OS (Not Supported)IBM z/Linux (Not Supported)

This property allows to specify a certain action to be performed whenever a share fails to be mounted after application startup in a permanent way. This includes incorrect credentials or mount points. Temporary problems, like a failure to resolve the host name or connect to the server, will continue to be retried in the background.

The property controls what happens when a failure happens in background mode. At this point, the application has already been started despite the share failing to be mapped during startup. So it is generally not a good idea to SHUTDOWN or take some other fatal action at this point. This property can be useful to run USER_<n> actions or log a message.

The default action is specified as NONE to do nothing.

Example:
wrapper.share.1.background.failure.action=USER_1

The full list of actions can be viewed on this page, but the most commonly used are the following:

  • DEBUG:

    will cause a debug message to be logged. This is only really useful in helping to understand when the action is fired.

  • SHUTDOWN:

    will stop the JVM as well as the Wrapper. Be careful when using this value, as a failure to mount a share in the background can occur at any time while the application is already running. If this happened, it would cause your application and the Wrapper to stop.

  • USER_<n>:

    will cause a user defined event to be fired. This can be either the sending of an email, or the execution of an external system command. The command could be anything from performing clean up operations to raising an SNMP trap.

  • NONE:

    will do nothing (the failure will not be followed by any action, and the Wrapper will continue).

Putting it all together