Package com.zfabrik.workers.home

Interface IWorkerProcess

public interface IWorkerProcess
A worker process is managed by the home process as explained in IHomeLayout.

Worker process component definitions have no resources beyond a property sheet. A worker process definition typically looks like this: 

 com.zfabrik.component.type=com.zfabrik.worker
 # worker configuration
 #
 # target states
 #
 worker.states=environment/webWorkerUp

 #
 # max worker thread pool concurrency
 #
 worker.concurrency=15


 #
 # debug port
 #
 worker.debug.port=5001
 #
 # timeout (in ms) before the worker will be forcefully killed at worker stop
 #
 worker.process.timeouts.termination=20000
 #
 # vm options
 #
 worker.process.vmOptions=\
  -Xmx128m -Xms128m -XX:+HeapDumpOnOutOfMemoryError \
  -Duser.language=en \
  -Dcom.sun.management.jmxremote.port=7778

  • Field Details

    • VMOPTS

      static final String VMOPTS
      ("worker.process.vmOptions") General virtual machine parameters for the worker process. See for example http://blogs.sun.com/watt/resource/jvm-options-list.html for a general overview. These params may be qualified further with the value of the system property "os.name" in the form of e.g. 
       worker.process.vmOptions.Windows\ 7=...
      In the presence of the latter these will be considered with preference.

      Note: Virtual machine parameters will be split by separator characters as in StringTokenizer. Test enclosed in double quotes will be considered a single token (embracing double quotes excluded). If it is necessary to pass parameters containing a space character for example, use quotes to enclose the option. If the option in turn requires to specify quotes, escape those using the backslash \ character.

      For example, 

       worker.process.vmOptions=-Dprop1=A -Dprop2=it works
      would resolve to system properties prop1="A", prop2="it" and a probably unexpected option works. Using instead 
       worker.process.vmOptions=-Dprop1=A "-Dprop2=it works"
      would resolve to system properties prop1="A", prop2="it works" as desired. If we intend to get prop2="it \"works\"", i.e. the string (delimited with single quotes for clarity) 'it "works"', we would use 
       worker.process.vmOptions=-Dprop1=A "-Dprop2=\"it works\""
      See Also:
      Constant Field Values

    • STATES

      static final String STATES
      ("worker.states") Target states (or dependency components) of the worker process (see above). The worker process, when starting, will try to attain these target states (or prepare these dependency components) and will try so again during each verification and synchronization.
      See Also:
      Constant Field Values

    • TO_START

      static final String TO_START
      ("worker.process.timeouts.start") Timeout in milliseconds. This time out determines when the worker process implementation will forcibly kill the worker process if it has not reported startup completion until then.
      See Also:
      Constant Field Values

    • TO_TERM

      static final String TO_TERM
      ("worker.process.timeouts.termination") Timeout in milliseconds. This time out determines when the worker process implementation will forcibly kill the worker process if it has not terminated after this timeout has passed since it was asked to terminate.
      See Also:
      Constant Field Values

    • TO_MSG

      static final String TO_MSG
      ("worker.process.timeouts.communication") Timeout in milliseconds. This time out is the default timeout that determines the time passed after which the worker process implementation will forcibly kill a worker process if a message request has not returned.
      See Also:
      Constant Field Values

    • WORKER_CONCURRENCY

      static final String WORKER_CONCURRENCY
      ("worker.concurrency") Size of application thread pool (see ApplicationThreadPool). In general this thread pool is used for application type work (e.g. for web requests or parallel execution within the application). This property helps achieving a simple but effective concurrent load control
      See Also:
      Constant Field Values

    • WORKER_DEBUG

      static final String WORKER_DEBUG
      ("worker.debug") Debugging for the worker process will be configured if this system property is set to true in the home process, e.g. by setting "-Dworker.debug=true" in the home process command line.

      This is not a profile parameter for the worker process definition. This is strictly the method to enable debugging for worker processes as launched by the home process. Otherwise the worker process will not be configured for debugging.

      See Also:
      Constant Field Values

    • DEBUG_PORT

      static final String DEBUG_PORT
      ("worker.debug.port") The debug port to use for this worker process. If this configuration is present and the home process is configured for debugging, so will the worker process. This port is subject to variant computation in the presence of detached worker processes. That is, this base port number will be increased by the variant number of the worker process that increases with every added instance, starting at 0. The variant number is the @-separated tail of the worker process name. See DEBUG_PARAMS for actual parameters added to the worker process command line.
      See Also:
      Constant Field Values

    • DEBUG_PARAMS

      static final String DEBUG_PARAMS
      ("worker.debug.params") In case debugging is enabled (see WORKER_DEBUG the params specified by this property will be added. These default to 
       "-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address={0}"
      The substitution {0} will be replaced by a debug port computed as in DEBUG_PORT.
      See Also:
      Constant Field Values

    • DEBUG_PARAMS_DEFAULT

      static final String DEBUG_PARAMS_DEFAULT
      ("-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address={0}") Default value for DEBUG_PARAMS.
      See Also:
      Constant Field Values

    • CLASSPATH

      static final String CLASSPATH
      ("worker.class.path") Classpath setting for the worker process. By default, the worker process inherits the class path from the home process. If that is not desired this setting allows to specify a different classpath. All paths should be specified relative to the current working folder which is typically the ${Z2_HOME}/bin folder. If the property value has a substitution field {0} it will be replaced by the home process classpath
      See Also:
      Constant Field Values

    • INHERITED_SYSPROPS

      static final String INHERITED_SYSPROPS
      ("worker.inheritedSystemProperties") A comma-separated list of system properties for the worker process. The value of some system properties may be forwarded on to the worker process. Currently this defaults to "com.sun.management.config.file,com.zfabrik.config,java.util.logging.config.file,com.zfabrik.dev.local.workspace,com.zfabrik.dev.local.repo,com.zfabrik.repo.mode,com.zfabrik.proxy.auth,java.library.path,com.zfabrik.mode,https.proxyPort,https.proxyHost,http.proxyPort,http.proxyHost,proxyPort,proxyHost,proxyUser,proxyPassword"
      See Also:
      Constant Field Values

    • INHERITED_SYSPROPS_DEFAULT

      static final String INHERITED_SYSPROPS_DEFAULT
      Default value of INHERITED_SYSPROPS.
      See Also:
      Constant Field Values

    • WORKER_REMOTE_JMX

      static final String WORKER_REMOTE_JMX
      ("worker.remoteJmx") JMX remote access for the worker process will be configured if this system property is set to true in the home process, e.g. by setting "-Dworker.remoteJMX=true" in the home process command line.

      This is not a profile parameter for the worker process definition. This is strictly the method to enable remote JMX port setting for worker processes as launched by the home process.

      See Also:
      Constant Field Values

    • JMX_PORT

      static final String JMX_PORT
      ("worker.jmx.port") The jmx port to use for this worker process. If this is set, the system property "com.sun.management.jmxremote.port" will be set via a system property declaration in the worker process command line. This port is subject to variant computation in the presence of detached worker processes. That is, this base port number will be increased by the variant number of the worker process that increases with every added instance, starting at 0. The variant number is the @-separated tail of the worker process name.
      See Also:
      Constant Field Values

    • JMX_PARAMS

      static final String JMX_PARAMS
      ("worker.jmx.params") In case remote JMX access is enabled (see WORKER_REMOTE_JMX the params specified by this property will be added. These default to 
       "-Dcom.sun.management.jmxremote.port={0}"
      The substitution {0} will be replaced by a debug port computed as in JMX_PORT.
      See Also:
      Constant Field Values

    • JMX_PARAMS_DEFAULT

      static final String JMX_PARAMS_DEFAULT
      ("-Dcom.sun.management.jmxremote.port={0}") Default value for JMX_PARAMS.
      See Also:
      Constant Field Values

    • TO_START_DEF

      static final String TO_START_DEF
      See Also:
      Constant Field Values

    • TO_TERM_DEF

      static final String TO_TERM_DEF
      See Also:
      Constant Field Values

    • TO_MSG_DEF

      static final String TO_MSG_DEF
      See Also:
      Constant Field Values

    • MSG_TARGET

      static final String MSG_TARGET
      msg header describing the target of a message
      See Also:
      Constant Field Values

    • MSG_TARGET_NODE

      static final String MSG_TARGET_NODE
      See Also:
      Constant Field Values

    • MSG_TARGET_ALL

      static final String MSG_TARGET_ALL
      See Also:
      Constant Field Values

    • MSG_TARGET_HOME

      static final String MSG_TARGET_HOME
      See Also:
      Constant Field Values

    • MSG_NODE

      static final String MSG_NODE
      msg header providing id of target node if one specific
      See Also:
      Constant Field Values

    • MSG_TIMEOUT

      static final String MSG_TIMEOUT
      msg header providing the time out of the message operation (per node). Can be provided as long or as string
      See Also:
      Constant Field Values

    • NOT_STARTED

      static final short NOT_STARTED
      See Also:
      Constant Field Values

    • STARTING

      static final short STARTING
      See Also:
      Constant Field Values

    • STARTED

      static final short STARTED
      See Also:
      Constant Field Values

    • DETACHED

      static final short DETACHED
      See Also:
      Constant Field Values

    • STOPPING

      static final short STOPPING
      See Also:
      Constant Field Values

  • Method Details

    • sendMessage

      Map<String,​Serializable> sendMessage​(Map<String,​Serializable> args, long timeout) throws IOException
      send a message to the process. Note: message sending happens completely synchronously. A message is just a name value map. All content must be serializable (preferrably string). Its return value is also just a map.
      Parameters:
      args - a map of name value pairs that will be serialized as strings to the slave
      timeout - timeout for message answering in ms.
      Returns:
      a result map
      Throws:
      IOException

    • sendMessage

      Map<String,​Serializable> sendMessage​(Map<String,​Serializable> args, long timeout, boolean killOnTimeOut) throws IOException
      send a message to the process. Note: message sending happens completely synchronously. A message is just a name value map. All content must be serializable (preferrably string). Its return value is also just a map.
      Parameters:
      args - a map of name value pairs that will be serialized as strings to the slave
      timeout - timeout for message answering in ms.
      killOnTimeOut - if true a timeout will lead to a process termination.
      Returns:
      a result map
      Throws:
      IOException

    • stop

      void stop()
      Stop this worker

    • stop

      void stop​(long timeout)
      Stop this worker with a non-default timeout. A timeout greater than 0 will ask the worker process to terminate gracefully. A timeout of 0 will stop the process immediately

    • start

      void start()
      start this worker

    • detach

      void detach()
      Detach this worker. Detaching means that this worker will no longer receive synchronization notifications from the home process. This worker is meant to complete its work and terminate gracefully.

    • isRunning

      boolean isRunning()
      Returns whether the current process is running. This is equivalent to being the latest and up or up and detached.

    • getState

      short getState()
      get the state of this worker

    • getComponentName

      String getComponentName()
      Get the worker process' component name

    • getName

      String getName()
      Get the worker process's instance technical name

    • getCreated

      long getCreated()
      Get the creation date of the worker process object (this is not necessarily the time it got started)

    • getDetachTime

      long getDetachTime()
      Get the time of detachment (if any). Returns <0 if not detached.