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.
Logger named net.jini.config to log information
at the following logging levels:
| Level | Description |
|---|---|
INFO | problems adding new prohibited methods |
FINE | 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 |
| 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.PrimitiveNO_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 Object |
getEntryInternal(String component,
String name,
Class 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 |
getEntryNames()
Returns a set containing the fully qualified names of all non-private entries defined for
this instance.
|
Class |
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 Object getEntryInternal(String component, String name, Class 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 datacomponent
and name, and using the value of data (unless it is
NO_DATA)NoSuchEntryException - 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 getEntryNames()
public Class 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 entryCopyright © GigaSpaces.