Rio Project 4.2 API Documentation

org.rioproject.exec
Class ServiceExecutor

java.lang.Object
  org.rioproject.exec.ServiceExecutor

public class ServiceExecutor
extends Object

Provides support to execute an external service. If the external service is a Java Virtual Machine, this utility will try to attach to the Java Virtual Machine using the JMX Attach API. This is only possible using Java 6 or greater. If the runtime is Java 5, external service utilization monitoring is not provided.

In order to obtain the process identifier required to attach to the exec'd JVM, the external process may create a pid file, containing the process identifier of the process. If this is the case, then configuring the deployment to declare the path of the produced pid file can be done.

If the exec'd process does not create a pid file, SIGAR is used to traverse the process tree to identify the parent process that exec'd the child JVM. If the parent process can be identified (see SigarHelper.matchChild(int, java.lang.String[]) the ServiceExecutor will attach to the JVM, and monitor CPU and Memory utilization. SIGAR is also used to monitor the real memory used by the exec'd JVM.

This class also provides configuration support for the following entries:

• shellTemplate
  

  Type:	String
  Default:	exec-template.sh
  Description:	The template to use for generating a script to exec a command. The script template must be loadable as a resource, and must provide the following token that get replaced by runtime values: ${command} The command to execute. This token eirs placed by the command to execute. ${pidFile} Rio creates a file that stores the pid of the executed command. This token is replaced by the name of the pid file to create ${commandLine} This token is replaced by the actual command line that is created to 'exec' the command above. Inoput arguments, standard error and output are also part of the created command line

• pidFileWaitTime
  

  Type:	int
  Default:	60
  Description:	The amount of time to wait for an exec'd service to create a pid file. The value is in seconds, where 60 seconds is the default. The minimum value for this property is 5 seconds, the maximum allowed 5 minutes. This value represents the maximum amount of time to wait. If the pid file is created prior to the timeout value, the utility proceeds immediately.

Notes:

• Hyperic SIGAR is licensed under the GPL with a FLOSS license exception, allowing it to be included with the Rio Apache License v2 distribution. If for some reason the GPL cannot be used with your distribution of Rio, remove the RIO_HOME/lib/hyperic directory.
• If SIGAR is removed, external service utilization monitoring is not provided.

Author:

Dennis Reedy

Constructor Summary

ServiceExecutor()

Method Summary

ProcessManager	exec()
ProcessManager	exec(ExecDescriptor exDesc)
ComputeResourceUtilization	getComputeResourceUtilization()
static void	main(String[] args)
void	preDestroy()
long	readPidFromFile(File f)
void	setExecDescriptor(ExecDescriptor execDescriptor)
void	setServiceBean(ServiceBean serviceBean)
void	setServiceBeanContext(ServiceBeanContext context)
void	terminate() Close the shell and release all used resources

Methods inherited from class java.lang.Object

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

Constructor Detail

ServiceExecutor

public ServiceExecutor()

Method Detail

setServiceBeanContext

public void setServiceBeanContext(ServiceBeanContext context)
                           throws JSBInstantiationException,
                                  IOException,
                                  ConfigurationException

Throws:

JSBInstantiationException

IOException

ConfigurationException

getComputeResourceUtilization

public ComputeResourceUtilization getComputeResourceUtilization()

setExecDescriptor

public void setExecDescriptor(ExecDescriptor execDescriptor)

setServiceBean

public void setServiceBean(ServiceBean serviceBean)

preDestroy

public void preDestroy()

exec

public ProcessManager exec()
                    throws IOException

Throws:

IOException

exec

public ProcessManager exec(ExecDescriptor exDesc)
                    throws IOException

Throws:

IOException

terminate

public void terminate()

Close the shell and release all used resources

readPidFromFile

public long readPidFromFile(File f)
                     throws IOException

Throws:

IOException

main

public static void main(String[] args)