com.sun.jini.tool

Class CheckConfigurationFile

java.lang.Object

com.sun.jini.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 Apache River release services and utilities are provided in the configentry subdirectory beneath the top-level directory of the Apache River 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[] { new Integer(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 Apache River 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

Field Summary

Fields

Modifier and Type	Field and Description
private static Class[]	primitives The primitive types
private static boolean	resinit
private static String	RESOURCE
private static ResourceBundle	resources

Constructor Summary

Constructors

Modifier	Constructor and Description
private	CheckConfigurationFile()

Method Summary

Methods

Modifier and Type	Method and Description
static boolean	check(ConfigurationFile config, Properties entries, ClassLoader loader, PrintStream err) Checks the format of a ConfigurationFile.
private static boolean	check(Object config, Properties entries, ClassLoader loader, PrintStream err) Checks the entries in config against the descriptions in entries, resolving expected types in loader.
private static boolean	check(String classPath, ClassLoader loader, boolean stdin, String[] configOptions, String entriesPath, PrintStream err) Checks the format of a configuration source file, using classes loaded from classPath and loader, requiring entries to match the names and values from entriesPath (unless entriesPath is null).
static boolean	check(String classPath, ClassLoader loader, String[] configOptions, String entriesPath, PrintStream err) Checks the format of a configuration source file.
private static Class	findClass(String name, ClassLoader loader) Returns the type with the specified name, including primitives and arrays, and checking the java.lang package for unqualified names.
private static Properties	getEntries(String files, PrintStream err) Returns information about the specified permitted entries, returning null if there is a problem loading properties from the files.
private static Constructor	getProviderConstructor(ClassLoader loader, PrintStream err) Returns the (Reader, String[], ClassLoader) constructor for the resource-specified configuration provider in loader.
private static String	getProviderName(URL url, PrintStream err) Returns the configuration provider class name specified in the contents of the URL.
private static String	getString(String key, PrintStream err) Returns a message from the resource bundle.
private static boolean	isAssignableFrom(Class dest, Class source) Checks if an object of type source can be assigned to a variable of type dest, where source is null for a null object.
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.
private static void	print(PrintStream err, String key, String val)
private static void	print(PrintStream err, String key, String[] vals)
private static void	print(PrintStream err, String keyPrefix, String source, Throwable t) If t is a ConfigurationException, uses the key keyPrefix+".fail", with source as the value for {0} and the localized message of t as the value for {1}.
private static String	typeName(Class type) Returns the name of a type, in source code format.
private static void	usage()

Methods inherited from class java.lang.Object

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

Field Detail

primitives

private static final Class[] primitives

The primitive types

RESOURCE

private static final String RESOURCE

resources

private static ResourceBundle resources

resinit

private static boolean resinit

Constructor Detail

CheckConfigurationFile

private CheckConfigurationFile()

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.

usage

private static void usage()

getEntries

private static Properties getEntries(String files,
                    PrintStream err)

Returns information about the specified permitted entries, returning null if there is a problem loading properties from the files.

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

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

Checks the format of a configuration source file, using classes loaded from classPath and loader, requiring entries to match the names and values from entriesPath (unless entriesPath is null). If stdin is true, reads the configuration source from standard input.

getProviderConstructor

private static Constructor getProviderConstructor(ClassLoader loader,
                                 PrintStream err)

Returns the (Reader, String[], ClassLoader) constructor for the resource-specified configuration provider in loader.

getProviderName

private static String getProviderName(URL url,
                     PrintStream err)

Returns the configuration provider class name specified in the contents of the URL.

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)

check

private static boolean check(Object config,
            Properties entries,
            ClassLoader loader,
            PrintStream err)

Checks the entries in config against the descriptions in entries, resolving expected types in loader.

findClass

private static Class findClass(String name,
              ClassLoader loader)
                        throws ClassNotFoundException

Returns the type with the specified name, including primitives and arrays, and checking the java.lang package for unqualified names. This method supports both internal names ('[I', '[Ljava.lang.Integer;', 'java.util.Map$Entry') and source level name ('int[]', 'Integer[]', 'java.util.Map.Entry').

Throws:

ClassNotFoundException

typeName

private static String typeName(Class type)

Returns the name of a type, in source code format.

isAssignableFrom

private static boolean isAssignableFrom(Class dest,
                       Class source)

Checks if an object of type source can be assigned to a variable of type dest, where source is null for a null object.

getString

private static String getString(String key,
               PrintStream err)

Returns a message from the resource bundle.

print

private static void print(PrintStream err,
         String keyPrefix,
         String source,
         Throwable t)

If t is a ConfigurationException, uses the key keyPrefix+".fail", with source as the value for {0} and the localized message of t as the value for {1}. Otherwise, uses the key keyPrefix+".err", with source as the value for {0}, the exception class name as the value for {1}, and the localized message of t as the value for {2}.

print

private static void print(PrintStream err,
         String key,
         String val)

print

private static void print(PrintStream err,
         String key,
         String[] vals)