Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

     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 }

     MethodCall:
       StaticMethodName ( ExprListopt )

     StaticMethodName:
       QualifiedIdentifier . Identifier

     ExprList:
       Expr
       ExprList , Expr

     Data:
       $data

     Loader:
       $loader

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 `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
Implementation Specifics:
  This implementation uses the `Logger` named `net.jini.config` to log information at the following logging levels:

  `net.jini.config`
  Level | Description
  --- | ---
  `INFO` | 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 inherited from class net.jini.config.AbstractConfiguration
`AbstractConfiguration.Primitive`

Field Summary

Fields inherited from interface net.jini.config.Configuration
`NO_DATA, NO_DEFAULT`

Constructor Summary
`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
`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.
`String` | `toString()` Returns a string representation of this object.

Methods inherited from class net.jini.config.AbstractConfiguration
`getEntry, getEntry, getEntry, validIdentifier, validQualifiedIdentifier`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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 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 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

### getEntryInternal

    protected Object getEntryInternal(String component,
                                      String name,
                                      Class 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:
    an object created using the information in the entry matching `component` and `name`, and using the value of `data` (unless it is `NO_DATA`)
  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 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 Class 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 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 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

### toString

    public String toString()

  Returns a string representation of this object.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved