org.apache.river.tool

Class CheckConfigurationFile

java.lang.Object

org.apache.river.tool.CheckConfigurationFile

public class CheckConfigurationFile
extends Object

Checks the format of the source for a ConfigurationFile. The source is specified with either a file, URL, or standard input, as well as with override options. The checks include syntax and static type checking, and require access to any application types mentioned in the source.

The following items are discussed below:

• Entry description files
• Command line options
• Examples for running CheckConfigurationFile

Entry description files

Checking of the source can be controlled by specifying one or more entry description files, each listing the names and types of entries that are allowed to appear in the source. Each entry description file is treated as a Properties source file, where each key is the fully qualified name of an entry (component.name) and each value specifies the expected type for that entry. Types should be specified in normal source code format, except that whitespace is not permitted between tokens. Types in the java.lang package may be unqualified, but fully qualified names must be used for other types (import statements are not supported). If any entry description files are supplied, then any public entry that appears in the source being checked, whose fully qualified name does not appear in any entry description file, or whose actual type is not assignable to the expected type, is treated as an error.

Entry description files for all of the River-Internet release services and utilities are provided in the configentry subdirectory beneath the top-level directory of the River-Internet release installation.

Here is a sample entry description file:

 comp.foo Integer[]
 comp.bar net.jini.core.constraint.MethodConstraints
 comp.baz long
 

Here is an associated sample configuration file:

 import net.jini.constraint.*;
 import net.jini.core.constraint.*;
 comp {
     foo = new Integer[] { Integer.valueOf(3) };
     bar = new BasicMethodConstraints(
               new InvocationConstraints(Integrity.YES, null));
     baz = 33L;
 }
 

Examples for running CheckConfigurationFile

This utility can be run from the command line, or by calling the check(String, ClassLoader, String[], String, PrintStream) or check(ConfigurationFile, Properties, ClassLoader, PrintStream) methods.

An example command line usage is:

 java -jar install_dir/lib/checkconfigurationfile.jar \
      -cp install_dir/lib/norm.jar:install_dir/lib/jsk-platform.jar \
      -entries install_dir/configentry/norm-transient \
      your-norm.config
 

where install_dir is the directory where the River-Internet release is installed, and your-norm.config is a configuration source file intended for use with the transient Norm service implementation. This command will print out any problems that it detects in the configuration file, including entries that are not recognized or have the wrong type for the Norm service.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

ConfigurationFile

Method Summary

Modifier and Type	Method and Description
static boolean	check(ConfigurationFile config, Properties entries, ClassLoader loader, PrintStream err) Checks the format of a ConfigurationFile.
static boolean	check(String classPath, ClassLoader loader, String[] configOptions, String entriesPath, PrintStream err) Checks the format of a configuration source file.
static void	main(String[] args) Command line interface for checking the format of source and override options for a ConfigurationFile, printing messages to System.err for any errors found.

Methods inherited from class java.lang.Object

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

Method Detail

main

public static void main(String[] args)

Command line interface for checking the format of source and override options for a ConfigurationFile, printing messages to System.err for any errors found. If errors are found, continues to check the rest of the source and overrides, and then calls System.exit with a non-zero argument.

The command line arguments are:

 [ -cp classpath ] [ -entries entrydescs ] location [ option... ]
 

or

 [ -cp classpath ] [ -entries entrydescs ] -stdin [ location [ option... ] ]
 

or

 -help
 

If the only argument is -help, a usage message is printed.

The classpath value for the -cp option specifies one or more directories and zip/JAR files, separated by the path separator character, where the application classes are located. A class loader that loads classes from this path will be created, with the extension class loader as its parent. If this option is not specified, the system class loader is used instead.

The entrydescs value for the -entries option specifies one or more entry description files, separated by the path separator character.

The location argument specifies the source file to be checked. If the -stdin option is used, then the actual source data will be read from standard input, and any location argument is simply used for identification purposes in error messages.

The remaining arguments specify any entry override values that should be passed to the ConfigurationFile constructor.

The class loader obtained above is used to resolve all expected types specified in the entry description files, and to obtain the configuration provider. The configuration provider class is found from the class loader in the same manner as specified by ConfigurationProvider. The resulting class must be ConfigurationFile or a subclass; if it is a subclass, it must have a public constructor with three parameters of type: Reader, String[], and ClassLoader. An instance of the provider is created by passing that constructor a Reader for the source file to be checked, the location and entry override values, and the class loader.

Parameters:

args - array of string arguments.

check

public static boolean check(String classPath,
                            ClassLoader loader,
                            String[] configOptions,
                            String entriesPath,
                            PrintStream err)

Checks the format of a configuration source file. Returns true if there are no errors, and false otherwise.

The classPath argument specifies one or more directories and zip/JAR files, separated by the path separator character, where the application classes are located. A class loader that loads classes from this path will be created, with loader as its parent. The ConfigurationFile is created with this class loader, and all expected types specified in entry description files are resolved in this class loader. If classPath is null, then loader is used instead.

The class loader is used to resolve all expected types specified in the entry description files, and to obtain the configuration provider. The configuration provider class is found from the class loader in the same manner as specified by ConfigurationProvider. The resulting class must be ConfigurationFile or a subclass; if it is a subclass, it must have a public constructor with three parameters of type: Reader, String[], and ClassLoader. An instance of the provider is created by passing that constructor a Reader for the source file to be checked, the location and entry override values, and the class loader.

Parameters:

classPath - the search path for application classes, or null to use the specified class loader

loader - the parent class loader to use for application classes if classPath is not null, otherwise the class loader to use for resolving application classes

configOptions - the configuration source file to check, plus any entry overrides

entriesPath - one or more entry description files, separated by the path separator character, or null

err - the stream to use for printing errors

Returns:

true if there are no errors, false otherwise

Throws:

NullPointerException - if loader, configOptions, or err is null

See Also:

check(ConfigurationFile, Properties, ClassLoader, PrintStream)

check

public static boolean check(ConfigurationFile config,
                            Properties entries,
                            ClassLoader loader,
                            PrintStream err)

Checks the format of a ConfigurationFile. Returns true if there are no errors, and false otherwise.

Parameters:

config - the ConfigurationFile to check

entries - the entry descriptions to use (where each key is a fully qualified entry name and each value is the expected type), or null

loader - the class loader to use for resolving type names used in the entry descriptions

err - the stream to use for printing errors

Returns:

true if there are no errors, false otherwise

Throws:

NullPointerException - if config, loader, or err is null

See Also:

check(String, ClassLoader, String[], String, PrintStream)