net.jini.config

Class ConfigurationFile

java.lang.Object

net.jini.config.AbstractConfiguration

net.jini.config.ConfigurationFile

All Implemented Interfaces:

Configuration

public class ConfigurationFile
extends AbstractConfiguration

Supplies objects needed to configure applications, such as Exporter or ProxyPreparer instances, or application-specific objects, constructed from data in a configuration source and override options, as well as data supplied in the call to getEntry. The configuration source is specified with a file or URL location, or as a character input stream. The contents of the configuration source consist of optional import statements followed by entries, grouped by component, that specify configuration objects using a subset of expression syntax in the Java(TM) programming language. Additional options specify values for individual entries, overriding any matching entries supplied in the configuration source.

Applications should normally use ConfigurationProvider to obtain Configuration instances, rather than referencing this class directly, so that the interpretation of configuration options can be customized without requiring code modifications.

The syntax of a configuration source is as follows, using the same grammar notation that is used in The Java Language Specification (JLS):

 Source:
   Importsopt Componentsopt

 Imports:
   Import
   Imports Import

 Import:
   import PackageName . * ;
   import PackageName . ClassName . * ;
   import PackageName . ClassName ;

 PackageName:
   QualifiedIdentifier

 ClassName:
   QualifiedIdentifier

 Components:
   Component
   Components Component

 Component:
   QualifiedIdentifier { Entriesopt }

 Entries:
   Entry
   Entries Entry

 Entry:
   EntryModifiersopt Identifier = Expr ;

 EntryModifiers:
   static
   private
   static private
   private static

 Expr:
   Literal
   TypeName . class
   EntryName
   ThisReference
   FieldName
   Cast
   NewExpr
   MethodCall
   Data
   Loader
   StringConcatenation 

 Literal:
   IntegerLiteral
   FloatingPointLiteral
   BooleanLiteral
   CharacterLiteral
   StringLiteral
   NullLiteral

 TypeName:
   ClassName
   ClassName [ ]
   PrimitiveType
   PrimitiveType [ ]

 EntryName:
   QualifiedIdentifier

 ThisReference:
   this

 FieldName:
   QualifiedIdentifier . Identifier

 Cast:
   ( TypeName ) Expr

 NewExpr:
   new QualifiedIdentifier ( ExprListopt )
   new QualifiedIdentifier [ ] { ExprListopt ,opt }

 MethodCall:
   StaticMethodName ( ExprListopt )

 StaticMethodName:
   QualifiedIdentifier . Identifier

 ExprList:
   Expr
   ExprList , Expr

 Data:
   $data

 Loader:
   $loader
 
 StringConcatenation:
   Expr + Expr 
 

The syntax of each override option is as follows:

 Override:
   EntryModifiersopt FullyQualifiedEntryName = Expr

 FullyQualifiedEntryName:
   QualifiedIdentifier . Identifier
 

For example, a simple configuration source file might look like the following:

 import java.util.HashSet;

 com.acme.ContainerUtility {
     container = new HashSet(containerSize);
     containerSize = 33;
 }
 

The productions for BooleanLiteral, CharacterLiteral, FloatingPointLiteral, Identifier, IntegerLiteral, NullLiteral, PrimitiveType, QualifiedIdentifier, and StringLiteral are the same as the ones used in the JLS. StringLiterals can refer to the values of system properties by using the syntax ${propertyName} within the StringLiteral, and can refer to the file name separator character by using the syntax ${/}. System property references cannot be nested. Expansion of system properties occurs when the entry is evaluated and, if there is a security manager, will result in its checkPropertyAccess method being called with the property name as its argument. Both StringLiterals and CharacterLiterals can use character and Unicode escape sequences. Standard comment syntax can also be used throughout.

Each Import specifies a class or group of classes which may be referred to using simple names, as specified in the JLS. Classes in the java.lang package are imported by default.

Each Component includes Entries which specify expressions to evaluate and return when getEntry is called with the associated component and entry name. More than one Component is allowed to specify the same name; all contribute entries for that component. For a given component, each entry name must be unique. If EntryModifiers contains the static keyword, then the entry is only evaluated once when it is first referenced. Otherwise, entries are evaluated at each reference, including each time an entry is referred to by another entry. Because static entries are only evaluated once (in the access control context of the first caller), care should be taken when passing instances of this class to callers with different access control contexts. If EntryModifiers contains the private keyword, then the entry may be referred to in other entries, but will not be considered by calls to getEntry, which will treat the entry name as not being defined. Entries may have reference, primitive, or null values. Entry values are converted to the requested type by assignment conversion, as defined in the JLS, with the restriction that the value is only considered a constant expression if it is either a StringLiteral with no system property references, another kind of Literal, or an EntryName that refers to another entry whose value is a constant expression. In particular, this restriction means that narrowing primitive conversions are not applied when the value is a reference to a static field, even if the field is a constant.

Override options are specified as the second and following elements of the options argument in this class's constructors. Each Override specifies a single entry, using the fully qualified name of the entry (component.name). The override replaces the matching entry in the configuration source, if any, including both its value and entry modifiers. Each Override option must specify a different FullyQualifiedEntryName. The contents of the Expr are evaluated in the context of any Imports defined in the configuration source.

The Expr for each Entry may be specified using a subset of the expression syntax in the Java programming language, supporting literals, references to static fields, casts, class instance creation (using the standard method invocation conversion and selection semantics, but not including creation of anonymous class instances), single dimensional array creation with an array initializer (but not multi-dimensional arrays or arrays declared with an explicit size), and static method invocation using a class name (also using standard method invocation conversion and selection semantics, but not permitting methods with a void return type). Expressions are interpreted in the unnamed package, although only public members may be accessed. The this expression may be used to refer to the containing ConfigurationFile instance itself.

The use of the + operator in a configuration source is also allowed, but it may be used only for string concatenation, as defined by the JLS. Using the + operator in an arithmetic expression results in a ConfigurationException being thrown.

The ConfigurationFile class provides built-in support for two special entry expressions, which are Identifiers that start with '$'. The $data expression, of type Object, may be used to refer to the data argument specified in a call to getEntry. Only non-static entries may refer to $data or other entries that refer to $data. Calling getEntry without specifying $data results in a ConfigurationException being thrown if the associated entry refers to $data. The $loader expression, of type ClassLoader, may be used to refer to the ClassLoader specified when creating the ConfigurationFile. If the ConfigurationFile was created using the context class loader either by not specifying a class loader or by specifying null for the class loader, then the caller must be granted RuntimePermission("getClassLoader") in order to evaluate an entry that refers to $loader. Subclasses can provide support for additional special entry expressions by supplying implementations of getSpecialEntryType and getSpecialEntry.

Entry expressions may also refer to other entries by name, using the simple entry name for entries within the same component, and the fully qualified entry name for entries in any component. A fully qualified name for which there is both an entry and a valid static field is interpreted as referring to the entry. An unqualified entry name for which there is an entry within the same component and is specified as a special entry expression will be interpreted as referring to the entry within that component.

Calls to the following methods are prohibited in order to avoid incorrect behavior because of their reliance on determining the ClassLoader or AccessControlContext of the caller:

• java.lang.Class.forName
• java.lang.ClassLoader.getSystemClassLoader
• java.lang.Package.getPackage
• java.lang.Package.getPackages
• java.lang.System.load
• java.lang.System.loadLibrary
• java.security.AccessController.doPrivileged
• java.sql.DriverManager.deregisterDriver
• java.sql.DriverManager.getConnection
• java.sql.DriverManager.getDriver
• java.sql.DriverManager.getDrivers
• net.jini.security.Security.doPrivileged

Attempting to evaluate an entry that calls any of these methods results in ConfigurationException being thrown. Additional prohibited methods may be specified by providing a resource named "net/jini/config/resources/ConfigurationFile.moreProhibitedMethods". Each line in the resource file should specify an additional prohibited method, represented by the fully qualified class name, a '.', and the method name for an additional prohibited method, with no spaces. The resource file must be encoded in UTF-8.

Any syntax error or problem reading from the configuration source or an override option results in a ConfigurationException being thrown.

If there is a security manager, the configuration source refers to the members of a class, and the class is in a named package, then this class calls the security manager's checkPackageAccess method with the class's package. Making this call in ConfigurationFile insures that the check is made despite any decisions within reflection to skip the check based on the class of the caller, which in this case will be ConfigurationFile rather than its caller. Note that implementations are permitted to make calls to reflection to access class members at arbitrary stack depths relative to that of the caller of ConfigurationFile; applications using security managers with custom implementations of the checkMemberAccess method should take this behavior into account.

Since:

2.0

Author:

Sun Microsystems, Inc.

Implementation Specifics:

This implementation uses the Logger named net.jini.config to log information at the following logging levels:

net.jini.config

Level	Description
SEVERE	problems adding new prohibited methods
FAILED	problems getting entries, including getting entries that are not found
FINE	returning default values
FINER	creating an instance of this class, getting existing entries, or adding new prohibited methods

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	ConfigurationFile.ArrayConstructor Represents constructing and initializing a single dimensional array.
private class	ConfigurationFile.Call Describes a call to a constructor, method, array constructor, or string concatenation operation.
private class	ConfigurationFile.Cast Represents a cast.
private class	ConfigurationFile.ClassLiteral Represents a Class literal.
private class	ConfigurationFile.ConstructorCall Describes a Constructor call
private class	ConfigurationFile.Entry Represents an entry.
static class	ConfigurationFile.ErrorDescriptor Class used to represent a syntax error encountered when parsing a configuration source or a problem encountered when attempting to return an existing entry or the type of an existing entry.
private class	ConfigurationFile.Literal Represents a simple literal value.
private class	ConfigurationFile.MethodCall Describes a method call.
private class	ConfigurationFile.NameRef Represents a reference to an entry, data specified by getEntry, or a field.
private class	ConfigurationFile.ParseNode Base class to represent parse results.
private class	ConfigurationFile.Parser Parses the input from the specified Reader and options, storing information about imports and entries by side effect.
private static class	ConfigurationFile.PushbackStreamTokenizer Defines a StreamTokenizer that resets sval, nval, and lineno when the pushBack method is called.
private class	ConfigurationFile.StringConcatenation
private class	ConfigurationFile.StringLiteral Represents a String literal.
private class	ConfigurationFile.ThisRef Represents a reference to this ConfigurationFile.

Nested classes/interfaces inherited from class net.jini.config.AbstractConfiguration

AbstractConfiguration.Primitive<T>

Field Summary

Fields

Modifier and Type	Field and Description
private static int	BYTE_INDEX Index of Byte.TYPE in primitives.
private ClassLoader	cl The class loader to use to resolve classes.
(package private) Map<String,String>	classImports Map of simple class names to the full class names that were explicitly imported.
private static PrivilegedAction	contextClassLoader Returns the current context class loader.
(package private) Map<String,ConfigurationFile.Entry>	entries Map from entry names to Entry instances.
(package private) static RuntimePermission	getClassLoaderPermission Permission needed to get the context class loader.
private static int	INT_INDEX Index of Integer.TYPE in primitives.
private String	location The location of the configuration source, or null if not specified.
private static String	moreProhibitedMethods The name of the resource that specifies more prohibited methods.
private boolean	nonNullLoaderSupplied Whether a non-null class loader was supplied.
(package private) List	onDemandImports List of packages or classes whose member classes should be imported on demand.
private int	override The override being parsed, or zero if not parsing an override.
private static Class[]	primitives The primitive types, in increasing order with respect to widening conversions.
private static Set<String>	prohibitedMethods The binary names of public, static methods that may not be called from within a configuration source, for all overloads.
private Object	resolveLock Lock for synchronizing calls to resolve entries.

Fields inherited from class net.jini.config.AbstractConfiguration

logger

Fields inherited from interface net.jini.config.Configuration

NO_DATA, NO_DEFAULT

Constructor Summary

Constructors

Constructor and Description
ConfigurationFile(Reader reader, String[] options) Creates an instance containing the entries parsed from the specified character stream and options, using the calling thread's context class loader for interpreting class names.
ConfigurationFile(Reader reader, String[] options, ClassLoader cl) Creates an instance containing the entries parsed from the specified character stream and options, using the specified class loader for interpreting class names.
ConfigurationFile(String[] options) Creates an instance containing the entries specified by the options, using the calling thread's context class loader for interpreting class names.
ConfigurationFile(String[] options, ClassLoader cl) Creates an instance containing the entries specified by the options, using the specified class loader for interpreting class names.

Method Summary

Modifier and Type	Method and Description
private static boolean	assignable(Class[] from, Class[] to) Returns true if values of the types specified in "from" can be passed to parameters of the types specified in "to".
(package private) static boolean	assignable(Class from, Class to) Returns true if values of type "from" can be passed to a parameter of type "to".
private String[]	checkOptions(String[] options) Checks that options contains no nulls, returning a non-null value.
private static void	checkPackageAccess(Class type) Check for permission to access the package of the specified class, if any.
private static boolean	compatible(Class[] parameterTypes, Class[] argumentTypes) Returns true if methods or constructors with the specified parameter types can accept arguments of the specified types.
(package private) static boolean	compatibleMethods(Class c1, Class c2) Returns true if the two classes have no public methods with the same name and parameter types but different return types.
(package private) static Object	convertPrimitive(Object obj, Class primitiveType) Converts a wrapper instance to an instance of the wrapper class for the specified primitive type.
(package private) String	expandStringProperties(String value, int lineno) Expands properties embedded in a string with ${some.property.name}.
(package private) Class	findClass(String name, int lineno, int override) Resolves a type name to a Class.
(package private) Class	findClass(String name, int lineno, int override, boolean returnIfNotFound) Resolves a type name to a Class.
(package private) Class	findClassExact(String name, int lineno, int override) Returns the class with this precise name, or null if not found, ignoring imports and not substituting '$' for nested classes.
(package private) Class	findClassNoImports(String name, int lineno, int override) Returns the class with the specified name, or null if not found, ignoring imports, but looking for nested classes.
(package private) Constructor	findConstructor(String typeName, Class[] argumentTypes, int lineno, int override) Resolve a type name to a constructor
(package private) Field	findField(String name, int lineno, int override) Resolves a field name to a field.
(package private) Method	findMethod(String fullName, Class[] argumentTypes, int lineno, int override) Resolves a method name to a method
(package private) static Class	findPrimitiveClass(String name) Returns the class if it names a primitive, otherwise null.
protected <T> Object	getEntryInternal(String component, String name, Class<T> type, Object data) Returns an object created using the information in the entry matching the specified component and name, and the specified data, for the requested type.
Set<String>	getEntryNames() Returns a set containing the fully qualified names of all non-private entries defined for this instance.
<T> Class<T>	getEntryType(String component, String name) Returns the static type of the expression specified for the entry with the specified component and name.
protected Object	getSpecialEntry(String name) Returns the value of the special entry with the specified name.
protected Class	getSpecialEntryType(String name) Returns the type of the special entry with the specified name.
(package private) <T> T	narrowingAssignable(Object from, Class<T> to) Returns the value to assign if the primitive value represented by the wrapper object in "from" can be assigned to parameters of type "to" using a narrowing primitive conversion, else null.
private void	oops(String what, int lineno, int override) Throws a ConfigurationException for an error described by the what argument, and for the specified line number and override.
private void	oops(String what, int lineno, int override, Throwable t) Throws a ConfigurationException for an error described by the what argument, for the specified line number and override, and caused by the specified evaluation exception, which may be null.
private void	oopsNoSuchEntry(String what) Calls throwConfigurationException with a default NoSuchEntryException.
protected void	throwConfigurationException(ConfigurationException defaultException, List errors) Allows a subclass of ConfigurationFile to control the ConfigurationException that is thrown.
String	toString() Returns a string representation of this object.
private static String	typesString(Class[] types) Returns a String describing the types in an argument list.

Methods inherited from class net.jini.config.AbstractConfiguration

getEntry, getEntry, getEntry, logThrow, validIdentifier, validQualifiedIdentifier

Methods inherited from class java.lang.Object

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

Field Detail

primitives

private static final Class[] primitives

The primitive types, in increasing order with respect to widening conversions.

INT_INDEX

private static final int INT_INDEX

Index of Integer.TYPE in primitives.

See Also:

Constant Field Values

BYTE_INDEX

private static final int BYTE_INDEX

Index of Byte.TYPE in primitives.

See Also:

Constant Field Values

prohibitedMethods

private static final Set<String> prohibitedMethods

The binary names of public, static methods that may not be called from within a configuration source, for all overloads. These methods are prohibited because they depend on knowing the class loader or access control context of their caller, which will be those of ConfigurationFile rather than of the caller of the ConfigurationFile constructor or getEntry. XXX: Update list if new methods like these are added. Find these methods by searching for ClassLoader.getCallerClassLoader, System.getCallerClass or Reflection.getCallerClass, which are used to make permission checks based on the caller's class loader. Note that there would be more kinds of security holes if ConfigurationFile permitted calls to instance methods. -tjb[5.Aug.2002]

moreProhibitedMethods

private static final String moreProhibitedMethods

The name of the resource that specifies more prohibited methods.

See Also:

Constant Field Values

contextClassLoader

private static final PrivilegedAction contextClassLoader

Returns the current context class loader.

getClassLoaderPermission

static final RuntimePermission getClassLoaderPermission

Permission needed to get the context class loader.

entries

final Map<String,ConfigurationFile.Entry> entries

Map from entry names to Entry instances.

classImports

final Map<String,String> classImports

Map of simple class names to the full class names that were explicitly imported.

onDemandImports

final List onDemandImports

List of packages or classes whose member classes should be imported on demand.

location

private String location

The location of the configuration source, or null if not specified.

override

private int override

The override being parsed, or zero if not parsing an override.

cl

private final ClassLoader cl

The class loader to use to resolve classes.

nonNullLoaderSupplied

private final boolean nonNullLoaderSupplied

Whether a non-null class loader was supplied.

resolveLock

private final Object resolveLock

Lock for synchronizing calls to resolve entries.

Constructor Detail

ConfigurationFile

public ConfigurationFile(String[] options)
                  throws ConfigurationException

Creates an instance containing the entries specified by the options, using the calling thread's context class loader for interpreting class names. The first option is a file or URL specifying the location of the configuration source; no source is specified if options is null, empty, or has "-" as the first element. The remaining options specify values for individual entries, overriding any matching entries supplied in the configuration source.

Parameters:

options - an array whose first element is the location of the configuration source and remaining elements specify override values for entries

Throws:

ConfigurationNotFoundException - if the specified source location cannot be found

ConfigurationException - if options is not null and any of its elements is null; or if there is a syntax error in the contents of the source or the overrides; or if there is an I/O exception reading from the source; or if the calling thread does not have permission to read the specified source file, connect to the specified URL, or read the system properties referred to in the source or overrides. Any Error thrown while creating the instance is propagated to the caller; it is not wrapped in a ConfigurationException.

ConfigurationFile

public ConfigurationFile(String[] options,
                         ClassLoader cl)
                  throws ConfigurationException

Creates an instance containing the entries specified by the options, using the specified class loader for interpreting class names. The first option is a file or URL specifying the location of the configuration source; no source is specified if options is null, empty, or has "-" as the first element. The remaining options specify values for individual entries, overriding any matching entries supplied in the configuration source. Specifying null for the class loader uses the current thread's context class loader.

Parameters:

options - an array whose first element is the location of the configuration source and remaining elements specify override values for entries

cl - the class loader to use for interpreting class names. If null, uses the context class loader.

Throws:

ConfigurationNotFoundException - if the specified source location cannot be found

ConfigurationException - if options is not null and any of its elements is null; or if there is a syntax error in the contents of the source or the overrides; or if there is an I/O exception reading from the source; or if the calling thread does not have permission to read the specified source file, connect to the specified URL, or read the system properties referred to in the source or overrides. Any Error thrown while creating the instance is propagated to the caller; it is not wrapped in a ConfigurationException.

ConfigurationFile

public ConfigurationFile(Reader reader,
                         String[] options)
                  throws ConfigurationException

Creates an instance containing the entries parsed from the specified character stream and options, using the calling thread's context class loader for interpreting class names. The constructor completes reading from the character input stream before returning, but does not close the stream. It is the responsibility of the caller to ensure that the character input stream is closed. The first option is used for the location of the configuration source when reporting errors; no location is specified if options is null, empty, or has "-" as the first element. The remaining options specify values for individual entries, overriding any matching entries supplied in the configuration source.

Parameters:

reader - the character input stream

options - an array whose first element is the location of the configuration source and remaining elements specify override values for entries

Throws:

ConfigurationException - if options is not null and any of its elements is null, or if there is a syntax error in the contents of the character input stream or the overrides, or if there is an I/O exception reading from the input stream, or if the calling thread does not have permission to read the system properties referred to in the input stream or overrides. Any Error thrown while creating the instance is propagated to the caller; it is not wrapped in a ConfigurationException.

NullPointerException - if reader is null

ConfigurationFile

public ConfigurationFile(Reader reader,
                         String[] options,
                         ClassLoader cl)
                  throws ConfigurationException

Creates an instance containing the entries parsed from the specified character stream and options, using the specified class loader for interpreting class names. The constructor completes reading from the character input stream before returning, but does not close the stream. It is the responsibility of the caller to ensure that the character input stream is closed. The first option is used for the location of the configuration source when reporting errors; no location is specified if options is null, empty, or has "-" as the first element. The remaining options specify values for individual entries, overriding any matching entries supplied in the configuration source. Specifying null for the class loader uses the current thread's context class loader.

Parameters:

reader - the character input stream

options - an array whose first element is the location of the configuration source and remaining elements specify override values for entries

cl - the class loader to use for interpreting class names. If null, uses the context class loader.

Throws:

ConfigurationException - if options is not null and any of its elements is null, or if there is a syntax error in the contents of the character input stream or the overrides, or if there is an I/O exception reading from the input stream, or if the calling thread does not have permission to read the system properties referred to in the input stream or overrides. Any Error thrown while creating the instance is propagated to the caller; it is not wrapped in a ConfigurationException.

NullPointerException - if reader is null

Method Detail

checkOptions

private String[] checkOptions(String[] options)
                       throws ConfigurationException

Checks that options contains no nulls, returning a non-null value. If the argument is not null, not empty, and its first element is not "-", sets location to the first element.

Throws:

ConfigurationException

throwConfigurationException

protected void throwConfigurationException(ConfigurationException defaultException,
                                           List errors)
                                    throws ConfigurationException

Allows a subclass of ConfigurationFile to control the ConfigurationException that is thrown. It must be called any time the ConfigurationFile implementation encounters a situation that would trigger a ConfigurationException. Such situations occur when attempting to parse a configuration source or when attempting to return an entry or the type of an entry and are fully documented in the specification for each ConfigurationFile method that throws a ConfigurationException.

The default ConfigurationFile implementation throws defaultException if defaultException is not null. If defaultException is null, the default implementation throws a ConfigurationException constructed from the error descriptors provided in errors. The default implementation throws java.lang.NullPointerException if errors is null, java.lang.IllegalArgumentException if errors is empty, and java.lang.ClassCastException if the contents of errors is not assignable to ErrorDescriptor.

Parameters:

defaultException - the exception the ConfigurationFile implementation would normally throw.

errors - list of errors encountered in parsing the configuration source or when attempting to return an entry or the type of an entry. This parameter may not be null, it must contain at least one element, and the elements of the list must be assignable to ErrorDescriptor. The order in which the errors appear in the list reflects the order in which they were encountered by the ConfigurationFile implementation.

Throws:

ConfigurationException - the subclass-specific ConfigurationException or the default exception passed in by the ConfigurationFile implementation.

Since:

2.1

getEntryInternal

protected <T> Object getEntryInternal(String component,
                                      String name,
                                      Class<T> type,
                                      Object data)
                               throws ConfigurationException

Returns an object created using the information in the entry matching the specified component and name, and the specified data, for the requested type. If the entry value is a primitive, then the object returned is an instance of AbstractConfiguration.Primitive. This implementation uses type to perform conversions on primitive values. Repeated calls with the same arguments may or may not return the identical object.

Specified by:

getEntryInternal in class AbstractConfiguration

Parameters:

component - the component being configured

name - the name of the entry for the component

type - the type of object requested

data - an object to use when computing the value of the entry, or Configuration.NO_DATA to specify no data

Returns:

T or Primitive

Throws:

NoSuchEntryException - if no matching entry is found

NullPointerException - if component, name, or type is null

ConfigurationException - if a matching entry is found but a problem occurs creating the object for the entry

See Also:

Configuration.getEntry

getEntryNames

public Set<String> getEntryNames()

Returns a set containing the fully qualified names of all non-private entries defined for this instance.

Returns:

a set containing the fully qualified names of all non-private entries defined for this instance

getEntryType

public <T> Class<T> getEntryType(String component,
                                 String name)
                          throws ConfigurationException

Returns the static type of the expression specified for the entry with the specified component and name.

Parameters:

component - the component

name - the name of the entry for the component

Returns:

the static type of the matching entry, or null if the value of the entry is the null literal

Throws:

NoSuchEntryException - if no matching entry is found

ConfigurationException - if a matching entry is found but a problem occurs determining the type of the entry. Any Error thrown while processing the entry is propagated to the caller; it is not wrapped in a ConfigurationException.

IllegalArgumentException - if component is not null and is not a valid QualifiedIdentifier, or if name is not null and is not a valid Identifier

NullPointerException - if either argument is null

getSpecialEntryType

protected Class getSpecialEntryType(String name)
                             throws ConfigurationException

Returns the type of the special entry with the specified name. Special entry names may be referred to from within other entries, but will not be considered by calls to getEntry. Implementations can assume that the argument to this method is a valid special entry name, which is an Identifier that starts with '$'. This method will be called when attempting to determine the type of a name expression that is a valid special entry name, does not refer to an existing entry, and is not a special entry expression supported by ConfigurationFile. The object returned by a call to getSpecialEntry with the same argument must be an instance of the class returned by this method.

The default implementation always throws NoSuchEntryException.

Parameters:

name - the name of the special entry

Returns:

the type of the special entry

Throws:

NoSuchEntryException - if the special entry is not found

ConfigurationException - if there is a problem determining the type of the special entry

getSpecialEntry

protected Object getSpecialEntry(String name)
                          throws ConfigurationException

Returns the value of the special entry with the specified name. Special entry names may be referred to from within other entries, but will not be considered by calls to getEntry. Implementations can assume that the argument to this method is a valid special entry name, which is an Identifier that starts with '$'. This method will be called when attempting to determine the value of a name expression which is a valid special entry name, does not refer to an existing entry, and is not a special entry expression supported by ConfigurationFile. The object returned by this method must be an instance of the class returned by a call to getSpecialEntryType with the same argument.

The default implementation always throws NoSuchEntryException.

Parameters:

name - the name of the special entry

Returns:

the value of the special entry

Throws:

NoSuchEntryException - if the special entry is not found

ConfigurationException - if there is a problem evaluating the special entry

findClass

Class findClass(String name,
                int lineno,
                int override)
         throws ConfigurationException

Resolves a type name to a Class. Primitive type names are supported.

Throws:

ConfigurationException

findClass

Class findClass(String name,
                int lineno,
                int override,
                boolean returnIfNotFound)
         throws ConfigurationException

Resolves a type name to a Class. Primitive type names are supported. If returnIfNotFound is true, then returns null rather than throwing an exception if the class is not found.

Throws:

ConfigurationException

findPrimitiveClass

static Class findPrimitiveClass(String name)

Returns the class if it names a primitive, otherwise null.

findClassNoImports

Class findClassNoImports(String name,
                         int lineno,
                         int override)
                  throws ConfigurationException

Returns the class with the specified name, or null if not found, ignoring imports, but looking for nested classes. Throws a ConfigurationException if the class is found but is not public, or has a non-public declaring class.

Throws:

ConfigurationException

findClassExact

Class findClassExact(String name,
                     int lineno,
                     int override)
              throws ConfigurationException

Returns the class with this precise name, or null if not found, ignoring imports and not substituting '$' for nested classes. Throws a ConfigurationException if the class is found but is not public, or has a non-public declaring class.

Throws:

ConfigurationException

findField

Field findField(String name,
                int lineno,
                int override)
         throws ConfigurationException

Resolves a field name to a field.

Throws:

ConfigurationException

checkPackageAccess

private static void checkPackageAccess(Class type)

Check for permission to access the package of the specified class, if any. Call this method prior to using reflection to access class members to insure that the access check is not skipped because of caller-based checks using ConfigurationFile instead of the caller of ConfigurationFile.

findMethod

Method findMethod(String fullName,
                  Class[] argumentTypes,
                  int lineno,
                  int override)
           throws ConfigurationException

Resolves a method name to a method

Throws:

ConfigurationException

findConstructor

Constructor findConstructor(String typeName,
                            Class[] argumentTypes,
                            int lineno,
                            int override)
                     throws ConfigurationException

Resolve a type name to a constructor

Throws:

ConfigurationException

compatible

private static boolean compatible(Class[] parameterTypes,
                                  Class[] argumentTypes)

Returns true if methods or constructors with the specified parameter types can accept arguments of the specified types.

assignable

private static boolean assignable(Class[] from,
                                  Class[] to)

Returns true if values of the types specified in "from" can be passed to parameters of the types specified in "to". The two arrays are assumed to be of the same length. A null type represents a null value.

assignable

static boolean assignable(Class from,
                          Class to)

Returns true if values of type "from" can be passed to a parameter of type "to". A null "from" type represents a null value. For primitive types, widening conversions are, with one exception, from types other than boolean and byte (the first legal type is char) and are only to the types int, long, float, or double. The one exception is the byte to short conversion, which is checked for separately.

narrowingAssignable

<T> T narrowingAssignable(Object from,
                          Class<T> to)

Returns the value to assign if the primitive value represented by the wrapper object in "from" can be assigned to parameters of type "to" using a narrowing primitive conversion, else null.

convertPrimitive

static Object convertPrimitive(Object obj,
                               Class primitiveType)

Converts a wrapper instance to an instance of the wrapper class for the specified primitive type.

compatibleMethods

static boolean compatibleMethods(Class c1,
                                 Class c2)

Returns true if the two classes have no public methods with the same name and parameter types but different return types.

typesString

private static String typesString(Class[] types)

Returns a String describing the types in an argument list.

expandStringProperties

String expandStringProperties(String value,
                              int lineno)
                       throws ConfigurationException

Expands properties embedded in a string with ${some.property.name}. Also treats ${/} as ${file.separator}.

Throws:

ConfigurationException

oops

private void oops(String what,
                  int lineno,
                  int override)
           throws ConfigurationException

Throws a ConfigurationException for an error described by the what argument, and for the specified line number and override.

Throws:

ConfigurationException

oops

private void oops(String what,
                  int lineno,
                  int override,
                  Throwable t)
           throws ConfigurationException

Throws a ConfigurationException for an error described by the what argument, for the specified line number and override, and caused by the specified evaluation exception, which may be null.

Throws:

ConfigurationException

oopsNoSuchEntry

private void oopsNoSuchEntry(String what)
                      throws ConfigurationException

Calls throwConfigurationException with a default NoSuchEntryException.

Throws:

ConfigurationException

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object