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 {@link ConfigurationProvider} to obtain{@link Configuration} instances, rather than referencing this classdirectly, 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 {@link SecurityManager#checkPropertyAccess checkPropertyAccess} method being calledwith 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 {@link 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 {@link 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 {@link 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 {@link #getSpecialEntryType getSpecialEntryType} and {@link #getSpecialEntry 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 {@link SecurityManager#checkPackageAccess checkPackageAccess} method with the class's package. Making this call inConfigurationFile 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 {@link SecurityManager#checkMemberAccess checkMemberAccess} method should take thisbehavior into account.
@author Sun Microsystems, Inc.
@since 2.0
@com.sun.jini.impl This implementation uses the {@link Logger} namednet.jini.config to log information at the following logging levels:
| Level | Description |
|---|---|
| {@link Level#INFO INFO} | problems adding new prohibitedmethods |
| {@link Levels#FAILED FAILED} | problems getting entries,including getting entries that are not found |
| {@link Level#FINE FINE} | returning default values |
| {@link Level#FINER FINER} | creating an instance of this class,getting existing entries, or adding new prohibited methods |
| |