GigaSpaces XAP 9.0 API

com.sun.jini.tool.envcheck
Class EnvCheck

java.lang.Object
  extended by com.sun.jini.tool.envcheck.EnvCheck

public class EnvCheck
extends Object

Tool used to perform validity checks on the run-time environment of a client or service. The output of this tool is a report; command-line options control the verbosity and severity level at which report entries are generated. A simple plugin architecture is implemented; a set of plugins implementing a variety of checks is bundled with the tool, and support is provided to allow additional plugins to be supplied by the user.

The following items are discussed below:

Running the Tool

This tool primarily validates the system properties and configuration files used when starting the target client or service. This is accomplished by providing the unmodified command line for launching the component as arguments to the tool. Thus, for a service designed to be run by the service starter having the hypothetical original command line:
 java -Djava.security.policy=mypolicy 
      -jar /jini/lib/start.jar mystart.config
 
the simplest invocation of the tool would be:
 java -jar /jini/lib/envcheck.jar
      java -Djava.security.policy=mypolicy 
           -jar /jini/lib/start.jar mystart.config
 
Note that the entire command line, including the java command, is supplied as arguments to the tool. The java command used to run the tool may be different than the java command invoked by the command line under test. The first token in the command line being analyzed must not begin with a '-' and must end with the string "java".

Processing Options

-traces
The implementation of a validity check may detect success or failure by handling an expected exception. By default, an error message will be generated in these cases, but the stack trace will be inhibited. This option is a hint that stack traces are desired. It is the responsibility of the individual plugin implementation to honor this option.

-explain
By default, the output of a validity check will be a short message with enough detail to allow a knowledgeable user to interpret it; however, it may not be understandable to a novice user. The -explain option is a hint that may result in the generation of additional output describing the purpose and context of the check. An explanation is output the first time its associated message is output, and is not repeated. It is the responsibility of the individual plugin implementation to honor this option.

-level info|warning|error
The tool supports three severity levels for message generation.

info
'success' messages or other non-failure oriented configuration data
warning
a condition or value has been detected that is 'legal', but which could result in unintended behavior. An example is the use of localhost in a codebase annotation.
error
a condition has been detected that is likely due to an error on the command line or in a configuration file. An example is assigning the value of a non-existant file name to the java.util.logging.config.file system property.

This option is used to set the level at which message records are generated. The default value is warning.

-plugin file
Identifies a JAR file containing user supplied plugins that will be run after the standard plugins are run. All of the necessary support classes and resources required to support the plugins must be included in this file. The file must also include a resource named META-INF/services/com.sun.jini.tool.envcheck.Plugin, which contains the class names of the plugins to run listed one per line. Every class listed must implement the com.sun.jini.tool.envcheck.Plugin interface. This option may be supplied zero or more times.

-security
A plugin specific option that is recognized by one of the bundled plugins. Specifying this option will activate a number of JAAS and JSSE checks. User supplied plugins wishing to recognize this option must implement the isPlugOption method of the Plugin interface.

Examples

The following example will analyze a command line used to start a user service. The command being analyzed defines a classpath and two system properties, and names a class containing a main method:

 java -jar /jini/lib/envcheck.jar -level info -explain -traces
      /usr/bin/java -cp mylib/myservice.jar:/jini/lib/jsk-platform.jar
                    -Djava.security.policy=mypolicy
                    -Djava.server.rmi.codebase=http://myhost/myservice-dl.jar
                    myservice.MyServiceImpl
 
In this case, the tool is limited to performing validity checks on the classpath, policy, and codebase values identified by the system properties and options provided on the service command line. The -level, -explain, and -traces options supplied will result in the most verbose output possible from the tool.

The following example will analyze a command line used to start reggie using the service starter. The command being analyzed uses a policy and service starter configuration located in the working directory:

 java -jar /jini/lib/envcheck.jar -level error
      /usr/bin/java -Djava.security.policy=mystarterpolicy
                    -jar /jini/lib/start.jar reggie.config
 
The tool can perform many more checks in this case because the bundled plugins include built-in knowledge about the service starter and its public configuration entries. The tool options used will minimize the output produced by the tool.

Bundled Plugins

A set of plugins are loaded automatically by the tool to perform some basic analysis.

If the command line being analyzed invokes the service starter, the tool will create a Configuration from the arguments of the command line being analyzed. Failure to create the Configuration will result in termination of the tool, otherwise the com.sun.jini.start.ServiceDescriptors provided by the Configuration are examined. The following checks are done for each ServiceDescriptor:

The following checks are done for each NonActivatableServiceDescriptor and each SharedActivatableServiceDescriptor The following checks are done for each SharedActivatableServiceDescriptor: The following checks are done for each SharedActivationGroupDescriptor: A subset of these checks are performed on the command line being analyzed: In all cases, check that the local host name does not resolve to the loopback address.


Constructor Summary
EnvCheck()
           
 
Method Summary
 String checkFile(String prop, String desc)
          Check for the existence of a file identified by a property supplied on the command line being analyzed.
 String[] getArgs()
          Get the command line arguments of the command being analyzed.
 String getClasspath()
          Get the classpath provided by the command line being analyzed.
 ServiceDescriptor[] getDescriptors()
          Return the ServiceDescriptors contained in the service starter configuration.
 SharedActivationGroupDescriptor getGroupDescriptor()
          Return the SharedActivationGroupDescriptor contained in the service starter configuration.
 String getJarToRun()
          Return the name of the executable JAR file supplied on the command line being analyzed.
 String getJavaCmd()
          Return the java command for the command line being analyzed.
 Properties getProperties()
          Return a copy of the properties that were specified on the command line being analyzed.
 String getProperty(String key)
          Return a property value that was specified on the command line being analyzed.
 Object launch(NonActivatableServiceDescriptor d, SharedActivationGroupDescriptor gd, String taskName)
          Launch a subtask using the environment defined by the given service descriptors.
 Object launch(NonActivatableServiceDescriptor d, SharedActivationGroupDescriptor gd, String taskName, String[] args)
          Launch a subtask using the environment defined by the given service descriptors.
 Object launch(String task)
          Launch a child VM using the java command, properties, and options supplied on the command line.
 Object launch(String javaCmd, Properties props, String[] opts, String[] args)
          Launch a subtask VM using the java command given by javaCmd.
 Object launch(String task, String[] args)
          Launch a child VM using the java command, properties, and options supplied on the command line being analyzed.
static void main(String[] args)
          The entry point for the tool.
 boolean printStacks()
          Return the flag indicating whether to output stack traces that result from a check.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EnvCheck

public EnvCheck()
Method Detail

main

public static void main(String[] args)
The entry point for the tool. The localization resource bundle is located, the plugins are loaded, and the checks are performed. The system property java.protocol.handler.pkgs for the tool VM is set to net.jini.url to ensure that the tool can manipulate HTTPMD URLs.

Parameters:
args - the command line arguments

getDescriptors

public ServiceDescriptor[] getDescriptors()
Return the ServiceDescriptors contained in the service starter configuration. If the command being analyzed does not invoke the service starter, a zero-length array will be returned.

Returns:
the descriptors in the starter configuration or an empty array

getGroupDescriptor

public SharedActivationGroupDescriptor getGroupDescriptor()
Return the SharedActivationGroupDescriptor contained in the service starter configuration. Returns null if there is no such descriptor, or if the command being analyzed does not invoke the service starter.

Returns:
the SharedActivationGroupDescriptor or null

getArgs

public String[] getArgs()
Get the command line arguments of the command being analyzed.

Returns:
the args

printStacks

public boolean printStacks()
Return the flag indicating whether to output stack traces that result from a check.


launch

public Object launch(String task,
                     String[] args)
Launch a child VM using the java command, properties, and options supplied on the command line being analyzed. If an executable JAR file was specified, the classpath of the child VM consists of the JAR file name augmented with the classpath of the tool and plugins. If a main class was specified, the classpath of the child VM consists of the -cp/-classpath option value of the command line being analyzed augmented with the classpath of the tool and plugins.

Parameters:
task - the class name of the task to launch, which must implement the SubVMTask interface
args - the arguments to pass to the main method of the task
Returns:
the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

launch

public Object launch(String task)
Launch a child VM using the java command, properties, and options supplied on the command line. If an executable JAR file was specified, the classpath of the child VM consists of the JAR file name augmented with the classpath of the tool and plugins. If a main class was specified, the classpath of the child VM consists of the -cp/-classpath option value of the command line being analyzed augmented with the classpath of the tool and plugins.

Parameters:
task - the class name of the task to launch, which must implement the SubVMTask interface
Returns:
the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

getProperty

public String getProperty(String key)
Return a property value that was specified on the command line being analyzed. Only properties explicitly defined on the command line will resolve to a value.

Parameters:
key - the name of the property
Returns:
the property value, or null if undefined

getProperties

public Properties getProperties()
Return a copy of the properties that were specified on the command line being analyzed. The caller may modify the returned properties object.

Returns:
the properties, which may be empty

launch

public Object launch(String javaCmd,
                     Properties props,
                     String[] opts,
                     String[] args)
Launch a subtask VM using the java command given by javaCmd. If javaCmd is null, the command to run is derived from the value of the java.home property of the tool VM. The first value in args must name a class that implements the SubVMTask interface. The props and opts arrays must contain fully formatted command line values for properties and options (i.e. "-Dfoo=bar" or "-opt"). opts must include a -cp or -classpath option and its value must completely specify the classpath required to run the subtask.

Parameters:
javaCmd - the java command to execute, or null to create another instance of the tool VM
props - properties to define, which may be null or empty
opts - options to define, which must include a classpath definition
args - arguments to pass to the child VM
Returns:
the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.
Throws:
IllegalArgumentException - if opts does not include a classpath definition, or if args[0] does not contain the name of a class that implements SubVMTask

launch

public Object launch(NonActivatableServiceDescriptor d,
                     SharedActivationGroupDescriptor gd,
                     String taskName)
Launch a subtask using the environment defined by the given service descriptors. Calling this method is equivalent to calling launch(d, g, taskName, null).

Parameters:
d - the services descriptor, which may be null
gd - the group descriptor, which may be nulltaskName - the name of the subtask to run
Returns:
the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

launch

public Object launch(NonActivatableServiceDescriptor d,
                     SharedActivationGroupDescriptor gd,
                     String taskName,
                     String[] args)
Launch a subtask using the environment defined by the given service descriptors.

If d and gd are both null, then calling this method is equivalent to calling launch(taskName, args).

If d is null and gd is non-null then the properties are taken from gd.getServerProperties() and the java.security.policy property is added or replaced with the value of gd.getPolicy(). The options are taken from gd.getServerOptions(), but any -cp/-classpath option is discarded; a -cp option is added that is the value of gd.getClasspath() augmented with the classpath of the tool and plugins. If gd.getServerCommand() is non-null, its value is used to invoke the child VM; otherwise the java command of the command line being analyzed is used. The arguments passed to the child VM consist of an array whose first element is taskName and whose remaining elements are taken from args.

If d is not null, but gd is null, then if d is an instance of SharedActivatableServiceDescriptor an IllegalArgumentException is thrown. Otherwise the properties and options are taken from the command line being analyzed. The java.security.policy property is added or replaced using the value of d.getPolicy(). The -cp/-classpath option is replaced with the value of d.getImportCodebase() augmented with the classpath of the tool and plugins. The arguments passed to the child VM consist of taskName followed by args if args is non-null, or followed by d.getServerConfigArgs() otherwise. The VM is invoked using the java command of the command line being analyzed.

if d and gd are both non-null then if d is an instance of SharedActivatableServiceDescriptor then the properties, options, and java command are taken from gd.getServerProperties(), gd.getServerOptions(), and gd.getServerCommand(); however, if the value of gd.getServerCommand() is null, the java command is taken from the command line being analysed. If d is not an instance of SharedActivatableServiceDescriptor then the properties, options, and java command are taken from the command line being analyzed. In all cases the java.security.policy property is added or replaced using the value of d.getPolicy(). The -cp/-classpath option is added or replaced with the value of d.getImportCodebase() augmented with the value of the classpath of the tool and plugins. The arguments passed to the child VM consist of taskName followed by args if args is non-null, or followed by d.getServerConfigArgs() otherwise.

Parameters:
d - the service descriptor, which may be null
gd - the group descriptor, which may be nulltaskName - the name of the subtask to run
args - the arguments to pass to the child VM, which may be null
Returns:
the result or exception returned by the subtask supplied as a serialized object written on the subtask's System.out stream.

getJavaCmd

public String getJavaCmd()
Return the java command for the command line being analyzed.

Returns:
the java command

checkFile

public String checkFile(String prop,
                        String desc)
Check for the existence of a file identified by a property supplied on the command line being analyzed.

Parameters:
prop - the name of the property
desc - a brief description of the file
Returns:
the property value, or null if undefined

getJarToRun

public String getJarToRun()
Return the name of the executable JAR file supplied on the command line being analyzed.

Returns:
the JAR file name, or null if the command line did not specify one.

getClasspath

public String getClasspath()
Get the classpath provided by the command line being analyzed. If getJarToRun() returns a non-null value then its value is returned. Otherwise the value supplied by the command line -cp/-classpath option is returned.

Returns:
the classpath supplied on the command line being analyzed.

GigaSpaces XAP 9.0 API

Copyright © GigaSpaces.