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=my_policy \
      -jar install_dir/lib/start.jar mystart.config
 
the simplest invocation of the tool would be:
 java -jar install_dir/lib/envcheck.jar \
      java -Djava.security.policy=my_policy \
           -jar install_dir/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 install_dir/lib/envcheck.jar -level info -explain -traces \
      java -cp mylib_dir/myservice.jar:/jini/lib/jsk-platform.jar \
           -Djava.security.policy=my_policy \
           -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 install_dir/lib/envcheck.jar -level error \
      java -Djava.security.policy=my_starterpolicy \
           -jar install_dir/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.


Nested Class Summary
(package private) static class EnvCheck.GetDescriptors
          A subtask which returns the service descriptors and service destructors supplied by the service starter configuration constructed from args.
private  class EnvCheck.Pipe
          An I/O redirection pipe.
 
Field Summary
private  String[] args
          the command line arguments of the command being analyzed
private static ResourceBundle bundle
          the localization resource bundle
(package private)  String classpath
          the classpath on the command line being checked
(package private) static String combinedClasspath
          the classpath of the tool, including the plugins (updated in run)
private  ServiceDescriptor[] descriptors
          the ServiceDescriptors obtained from the starter config
(package private)  String jarToRun
          the executable JAR file on the command line being checked
private  String javaCmd
          the java command on the command line being checked
(package private)  String mainClass
          the main class on the command line being checked
(package private)  String[] options
          the options on the command line being checked (never null)
(package private) static ArrayList pluginJarList
          the list of plugins supplied via the -plugin option
private  ArrayList pluginList
          the list of plugins instances to run
(package private)  ClassLoader pluginLoader
          the class loader for loading plugins
private  boolean printStackTraces
          flag controlling the display of stack traces in the output
(package private)  Properties properties
          the properties on the command line being checked (never null)
 
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.
private static void findPlugins(String[] cmdLine)
          Search the command line for user supplied plugin definitions and place them in the internal plugin list.
 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.
private  String getString(String key)
          Helper to print a localized string
private  String getString(String key, String val)
          Helper to print a localized string
private  boolean isPluginOption(String arg)
          Check whether arg is a plugin specific option.
 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.
private  void loadConfiguration()
          Instantiate the service starter configuration if the command line being analyzed runs the service starter.
private  void loadPlugins()
          Load the plugin classes.
static void main(String[] args)
          The entry point for the tool.
private  void parseArgs(String[] cmdLine)
          Parse the command line, identifying options for the tool and parsing the VM, system properties, options, JAR/main class and arguments for the command line being tested.
 boolean printStacks()
          Return the flag indicating whether to output stack traces that result from a check.
private  void run(String[] cmdLine)
          Perform the runtime checks.
private static void usage()
          Output the usage message.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pluginList

private ArrayList pluginList
the list of plugins instances to run


printStackTraces

private boolean printStackTraces
flag controlling the display of stack traces in the output


args

private String[] args
the command line arguments of the command being analyzed


descriptors

private ServiceDescriptor[] descriptors
the ServiceDescriptors obtained from the starter config


bundle

private static ResourceBundle bundle
the localization resource bundle


javaCmd

private String javaCmd
the java command on the command line being checked


options

String[] options
the options on the command line being checked (never null)


properties

Properties properties
the properties on the command line being checked (never null)


classpath

String classpath
the classpath on the command line being checked


mainClass

String mainClass
the main class on the command line being checked


jarToRun

String jarToRun
the executable JAR file on the command line being checked


pluginJarList

static ArrayList pluginJarList
the list of plugins supplied via the -plugin option


pluginLoader

ClassLoader pluginLoader
the class loader for loading plugins


combinedClasspath

static String combinedClasspath
the classpath of the tool, including the plugins (updated in run)

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

usage

private static void usage()
Output the usage message.


getString

private String getString(String key)
Helper to print a localized string

Parameters:
key - the resource key

getString

private String getString(String key,
                         String val)
Helper to print a localized string

Parameters:
key - the resource key
val - the value parameter expected by the message

findPlugins

private static void findPlugins(String[] cmdLine)
Search the command line for user supplied plugin definitions and place them in the internal plugin list.

Parameters:
cmdLine - the original command line args

parseArgs

private void parseArgs(String[] cmdLine)
Parse the command line, identifying options for the tool and parsing the VM, system properties, options, JAR/main class and arguments for the command line being tested. The -plugin option is ignored by this parser since they must have been processed earlier.

Parameters:
cmdLine - the original 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

run

private void run(String[] cmdLine)
Perform the runtime checks. If any user plugins were supplied, construct a class loader capable of loading them and modify combinedClasspath to make the classes available to subtasks. Load the plugins and parse the command line. The plugins must be available to the parser so that plugin specific options can be checked for. Load the service starter configuration if the service starter is being invoked. Execute all of the plugin classes in the order loaded.

Parameters:
cmdLine - the original command line arguments

isPluginOption

private boolean isPluginOption(String arg)
Check whether arg is a plugin specific option. The isPluginOption method of every plugin is called in case an option is shared among multiple plugins.

Parameters:
arg - the argument to check
Returns:
true if any plugin's isPluginOption method returns true

loadConfiguration

private void loadConfiguration()
Instantiate the service starter configuration if the command line being analyzed runs the service starter. This is assumed to be true if the command line specified an executable JAR file named start.jar and if that file resides in the same directory as a file named jsk-platform.jar. Extract and save all of the service descriptors and service destructors from the configuration. If a ConfigurationException is thrown the tool will exit. If there are no ServiceDescriptor or ServiceDestructor entries supplied by the configuration a error is generated and a normal return is done. The instantiation of the configuration is done in a child process using the VM, properties, options and arguments supplied in the command line under test.


loadPlugins

private void loadPlugins()
Load the plugin classes. All of the resources named META-INF/services/com.sun.jini.tool.envcheck.Plugin are read; each such resource is expected to contain a list of plugin class names, one per line (white space is trimmed). The corresponding classes are loaded and saved. Any other exceptions thrown while processing the plugin JAR files will cause the tool to exit.


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.


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.