java.rmi.server
Class SecureExportFile

java.lang.Object
  |
  +--java.rmi.server.SecureExportFile

public class SecureExportFile
extends java.lang.Object

Allows secure export descriptors to be constructed from configuration files. An instance of this class contains zero or more descriptor information entries, the contents of which are parsed from input streams. This class is not synchronized; if multiple threads access an instance concurrently, and at least one of the threads calls the read method, external synchronization must be used to ensure correct operation.

The syntax of an input stream is as follows, using the same grammar notation that is used in The JavaTM Language Specification:

 Contents:
   ExportDesc
   Contents ExportDesc

 ExportDesc:
   export default { DescElementsopt }
   export Name { DescElementsopt }

 DescElements:
   DescElement
   DescElements DescElement

 DescElement:
   method default { ConstraintDescsopt }
   method MethodList { ConstraintDescsopt }
   factory { ObjectList }
   endpoint { ObjectList }

 MethodList:
   MethodDesc
   MethodList , MethodDesc

 MethodDesc:
   Identifier
   Identifier ( TypeListopt )

 TypeList:
   Type
   TypeList , Type
   
 ConstraintDescs:
   ConstraintDesc
   ConstraintDescs ConstraintDesc

 ConstraintDesc:
   require { ObjectList }
   prefer { ObjectList }

 ObjectList:
   ObjectExpr
   ObjectList , ObjectExpr

 ObjectExpr:
   Name
   NewExpr

 ExprList:
   Expr
   ExprList , Expr

 Expr:
   Literal
   Name
   Name.class
   NewExpr

 NewExpr:
   new Name ( ExprListopt )
   new Name [ ] { ExprListopt }
 
The productions for Identifier, IntegerLiteral, Literal, Name and Type are the same as the ones used in The Java Language Specification, except that whitespace is not permitted between tokens. Standard comment syntax can also be used throughout.

Each ExportDesc is a single descriptor entry. The name default can be used to specify the default entry. It is an error if an input stream contains more than one ExportDesc with the same name. A method default DescElement specifies the defaultConstraints parameter for the SecureExportDesc constructor. The other method DescElements are used to construct the methodConstraints parameter for the SecureExportDesc constructor. A MethodConstraints is constructed for each MethodDesc. The Identifier in a MethodDesc specifies the method name, and the TypeList specifies the parameter types; absence of a TypeList indicates wildcard parameter types. A factory DescElement is used to construct SecureServerEndpointFactory instances, which will be used to generate endpoints to pass to the SecureExportDesc constructor. An endpoint DescElement is used to construct SecureServerEndpoint instances to pass to the SecureExportDesc constructor. It is an error if there is more than one method default, factory, or endpoint DescElement in a given entry, or if there is both a factory and an endpoint DescElement in a given entry.

A require ConstraintDesc specifies constraint requirements, and a prefer ConstraintDesc specifies constraint preferences. There can be any number of each in a given DescElement.

The remaining syntax is a small subset of the language's expression syntax, supporting literals, references to constants (including class constants), class instance creation (using the standard method invocation conversion and selection semantics), and array creation. Expressions are evaluated at the time they are parsed. Class names are resolved using the context classloader of the current thread. Classes from the packages java.lang and java.rmi.constraint can be named without package qualification; other class names must be fully qualified.

Any syntax error, evaluation error, or problem reading from the input stream results in an IOException being thrown, and the remainder of the stream is not read.

Since:
1.4

Constructor Summary
SecureExportFile()
          Creates an instance containing no entries.
SecureExportFile(java.io.Reader reader)
          Creates an instance containing the entries parsed from the specified input stream.
SecureExportFile(java.lang.String fileOrURL)
          Creates an instance containing the entries parsed from the contents of the specified file or URL.
 
Method Summary
 SecureExportDesc get(java.lang.String descName, javax.security.auth.Subject serverSubject)
          Returns a secure export descriptor created using the specified server subject and the information in the entry matching the specified name.
 java.util.Set keySet()
          Returns an unmodifiable set of the names of all of the entries.
 void read(java.io.Reader reader, boolean override)
          Adds the entries parsed from the specified input stream.
 void read(java.lang.String fileOrURL, boolean override)
          Adds the entries parsed from the contents of the specified file or URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SecureExportFile

public SecureExportFile()
Creates an instance containing no entries.

SecureExportFile

public SecureExportFile(java.lang.String fileOrURL)
                 throws java.io.IOException
Creates an instance containing the entries parsed from the contents of the specified file or URL.
Parameters:
fileOrURL - file name or URL
Throws:
java.io.IOException - if there is a problem opening an input stream for the specified file or URL, or if there is a syntax error, evaluation error, or problem reading from the input stream
NullPointerException - if the parameter is null

SecureExportFile

public SecureExportFile(java.io.Reader reader)
                 throws java.io.IOException
Creates an instance containing the entries parsed from the specified input stream.
Parameters:
reader - the input stream
Throws:
java.io.IOException - if there is a syntax error, evaluation error, or problem reading from the input stream
NullPointerException - if the parameter is null
Method Detail

read

public void read(java.lang.String fileOrURL,
                 boolean override)
          throws java.io.IOException
Adds the entries parsed from the contents of the specified file or URL. If override is true, an entry parsed from the stream replaces any existing entry with the same name (if one exists). If override is false, an entry parsed from the stream is discarded if there is an existing entry with the same name.
Parameters:
fileOrURL - file name or URL
override - true if an entry parsed from the stream should replace any existing entry with the same name, false if an entry parsed from the stream should be discarded if there is an existing entry with the same name
Throws:
java.io.IOException - if there is a problem opening an input stream for the specified file or URL, or if there is a syntax error, evaluation error, or problem reading from the input stream
NullPointerException - if the first parameter is null

read

public void read(java.io.Reader reader,
                 boolean override)
          throws java.io.IOException
Adds the entries parsed from the specified input stream. If override is true, an entry parsed from the stream replaces any existing entry with the same name (if any). If override is false, an entry parsed from the stream is discarded if there is an existing entry with the same name.
Parameters:
reader - the input stream
override - true if an entry parsed from the stream should replace any existing entry with the same name, false if an entry parsed from the stream should be discarded if there is an existing entry with the same name
Throws:
java.io.IOException - if there is a syntax error, evaluation error, or problem reading from the input stream
NullPointerException - if the first parameter is null

get

public SecureExportDesc get(java.lang.String descName,
                            javax.security.auth.Subject serverSubject)
                     throws UnsupportedSecurityException
Returns a secure export descriptor created using the specified server subject and the information in the entry matching the specified name. If there is no entry with a name that exactly matches the specified name, the default entry is used. The name "default" can be used to obtain the default entry. If there is no entry with the exact name and no default entry exists, null is returned. If the matching entry contains SecureServerEndpoint instances, the server subject parameter is ignored, and those endpoints are passed directly to the SecureExportDesc constructor along with the default and method-specific server constraints. If the matching entry contains SecureServerEndpointFactory instances, the getServerEndpoint method of each factory is invoked with the server subject as a parameter to produce a list of endpoints, and then those endpoints are passed to the SecureExportDesc constructor along with the default and method-specific server constraints. If any getServerEndpoint call throws an exception, that exception is thrown to the caller. If the matching entry contains no factories or endpoints, the server subject is passed to the SecureExportDesc constructor along with the default and method-specific server constraints. In all cases, if the SecureExportDesc constructor throws an exception, that exception is thrown to the caller.
Parameters:
descName - the descriptor entry name
serverSubject - the server subject, or null
Returns:
a secure export descriptor created using the specified server subject and the information in the entry matching the specified name
Throws:
UnsupportedSecurityException - if the constraints for a remote method cannot be satisfied, or a factory cannot produce a server endpoint for the specified server subject
NullPointerException - if descName is null
java.lang.IllegalArgumentException - if any two method constraints specify the same method name and parameter types, or an endpoint is specified that does not support the constraints of any remote methods

keySet

public java.util.Set keySet()
Returns an unmodifiable set of the names of all of the entries. If a default entry exists, the name "default" is included in the set.
Returns:
an unmodifiable set of the names of all of the entries


Copyright © 2000 Sun Microsystems, Inc. All rights reserved