File System Service Provider for JNDI

------------------------------------- File System Service Provider for JNDI ------------------------------------- This is the Early Access 4 release of the JNDI/File system service provider. Please send feedback to jndi@java.sun.com 1.0 INTRODUCTION ---------------- JNDI offers a universal naming API and a standardized way to store objects in a namespace. The File System Service Provider supports these features for a local or networked file system. Its purpose is two-fold: 1) Allow clients to traverse the file system namespace using JNDI's context interface. 2) Allow clients to store Java objects in the file system. These two separate functions are actually handled by two different providers (i.e. classes). The first class handles accessing the file system and can be used independently of the second. The second class handles storage of Java objects and is used in conjunction with the first (i.e. it is a subclass of the first). 2.0 CONFORMANCE --------------- The File System Service Provider accesses the file system using the java.io.File class. The file system can be local or networked--the only requirement is that it is accessible using the java.io.File class. Use of the java.io.File class makes the service provider platform independent. Therefore, the File System Service Provider conforms to the file system of whatever platform it is executing on. The File System Service provider treats each directory as a context and each file as a "File" object stored in the context representing the file's parent directory. Java objects can also be stored in file system. Each object is stored in an invisible file as a set of properties that the service provider uses to re-construct the object. The file has the same format used by java.util.Properties. Although the file can be viewed and edited, the properties within have little meaning outside of the Service Provider. 3.0 ENVIRONMENT PROPERTIES -------------------------- The following JNDI environment properties are relevant to the File System Service Provider: java.naming.factory.initial This environment property is used to select the File System service provider. It's not actually used by the provider itself. It specifies the class name of the initial context factory for the provider. It can have one of two values. The first choice names the class responsible for File System access. For example: java.naming.factory.initial=com.sun.jndi.fscontext.FSContextFactory The second choice names the class--a subclass of FSContextFactory--which adds the ability to lookup and store Java objects in the File System. For example: java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory If this environment property is not set to one of these two values, then the provider cannot start. java.naming.provider.url Specifies the file to be used as the root context. It must be a file URL representing a directory in the file system. For Example: file:///home/kafka this URL will cause the provider to use the directory named "kafka" in the directory "home" in the root directory as the base context. Performing a list() on the initial context would be equivalent to typing the UNIX command "ls" in the directory "/home/kafka" directory. If this environment property is not set, calls that use the provider will fail. java.naming.factory.object Specifies the object factories to be used when retrieving Java objects bound in the file system. See the JNDI Documentation for more information. 4.0 TYPES OF OBJECTS AND HOW OBJECTS ARE NAMED ---------------------------------------------- Contexts and objects are named using the naming scheme of the local or networked file system of the underlying platform. When naming objects, use either the javax.naming.Name calls or Context.composeName() calls (which use the javax.naming.Name interface) or construct strings with java.io.File.separator. This will ensure that the code will work on any file system, regardless of its naming scheme. A context in the File System Service Provider is simply a directory. Calling list() on a context is equivalent to issuing the UNIX command "ls" on the corresponding directory. The initial context produced refers to the directory specified in the java.naming.provider.url. Files are represented as objects of class java.io.File bound to the context representing the file's parent directory. All objects are named relative to the context on which you make a call. For example, if the local file system looks like this: (root) | "home" | "kafka" | --------------------- | | "metamorphosis" "castle" | ----------------- | | | "ch1" "ch2" "ch3" Then, an initial context could be created using the following code: Hashtable env = new Hashtable(11); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.fscontext.RefFSContextFactory"); env.put(Context.PROVIDER_URL, "file:///home/kafka"); Context initCtx = new InitialContext(env); The following call on the initial context would cause the context representing "metamorphosis" to be returned: Context ctx = initCtx.lookup("metamorphosis"); The following call on the initial context would return the File object representing "ch1" to be returned: Context ctx = initCtx.lookup("castle" + File.separator + "ch1"); Java objects can be stored in the File System under the following conditions: 1) The initial factory is RefFSContextFactory (not FSContextFactory) 2) The object is of type java.naming.Reference or implements java.naming.Referenceable (see JNDI documentation) If these conditions are met, an object can be stored in the following way: class MyObject implements Referenceable { ... } MyObject obj = new MyObject(); initCtx.bind("metamorphosis/myBoundObject", obj); To retrieve an object, the object factory must be made available to JNDI. In the following example, the appropriate property is added to the context's environment before calling lookup(): initCtx.addToEnvironment(Context.OBJECT_FACTORIES, "MyObjectFactory"); MyObject obj = initCtx.lookup("metamorphosis/myBoundObject"); 5.0 API MAPPINGS ---------------- This section describes how the various JNDI calls are mapped to the File System. addToEnvironment() Adds the given property and value to the context's environment. bind() Binds the given object to the named context. The object must be Reference or implement Referenceable. The bound object is stored as a set of properties in a file called ".bindings". Its parent directory is the directory corresponding to the context in which the object is bound. This only works with RefFSContext. close() Releases the context's internal data structures. composeName() Concatenates two names. createSubcontext() Creates a subcontext by creating the corresponding directory in the file system. destroySubcontext() Destroys a subcontext by deleting the corresponding directory in the file system. getEnvironment() Returns the context's environment. getNameParser() Returns a name parser for file system names. lookup() lookupLink() Returns the object named relative to the context. The object may be a Context (if the name refers to a directory), a File (if the name refers to a file), or an arbitrary object that was previously bound in the file system.