public class ConfigurationFile extends AbstractConfiguration
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
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.
| Modifier and Type | Class and Description |
|---|---|
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.
|
AbstractConfiguration.Primitive<T>NO_DATA, NO_DEFAULT| 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.
|
| Modifier and Type | Method and Description |
|---|---|
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.
|
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.
|
getEntry, getEntry, getEntry, validIdentifier, validQualifiedIdentifierpublic ConfigurationFile(String[] options) throws ConfigurationException
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.options - an array whose first element is the location of the
configuration source and remaining elements specify override values for
entriesConfigurationNotFoundException - if the specified source location
cannot be foundConfigurationException - 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.public ConfigurationFile(String[] options, ClassLoader cl) throws ConfigurationException
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.options - an array whose first element is the location of the
configuration source and remaining elements specify override values for
entriescl - the class loader to use for interpreting class names. If
null, uses the context class loader.ConfigurationNotFoundException - if the specified source location
cannot be foundConfigurationException - 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.public ConfigurationFile(Reader reader, String[] options) throws ConfigurationException
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.reader - the character input streamoptions - an array whose first element is the location of the
configuration source and remaining elements specify override values for
entriesConfigurationException - 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 nullpublic ConfigurationFile(Reader reader, String[] options, ClassLoader cl) throws ConfigurationException
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.reader - the character input streamoptions - an array whose first element is the location of the
configuration source and remaining elements specify override values for
entriescl - the class loader to use for interpreting class names. If
null, uses the context class loader.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 nullprotected void throwConfigurationException(ConfigurationException defaultException, List errors) throws ConfigurationException
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.
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.ConfigurationException - the subclass-specific
ConfigurationException or the default exception passed in
by the ConfigurationFile implementation.protected <T> Object getEntryInternal(String component, String name, Class<T> type, Object data) throws ConfigurationException
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.getEntryInternal in class AbstractConfigurationcomponent - the component being configuredname - the name of the entry for the componenttype - the type of object requesteddata - an object to use when computing the value of the entry, or
Configuration.NO_DATA to specify no dataNoSuchEntryException - if no matching entry is foundNullPointerException - if component,
name, or type is nullConfigurationException - if a matching entry is found but a
problem occurs creating the object for the entryConfiguration.getEntrypublic Set<String> getEntryNames()
public <T> Class<T> getEntryType(String component, String name) throws ConfigurationException
component - the componentname - the name of the entry for the componentnull if
the value of the entry is the null literalNoSuchEntryException - if no matching entry is foundConfigurationException - 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
IdentifierNullPointerException - if either argument is nullprotected Class getSpecialEntryType(String name) throws ConfigurationException
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.
name - the name of the special entryNoSuchEntryException - if the special entry is not foundConfigurationException - if there is a problem determining the
type of the special entryprotected Object getSpecialEntry(String name) throws ConfigurationException
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.
name - the name of the special entryNoSuchEntryException - if the special entry is not foundConfigurationException - if there is a problem evaluating the
special entry