# File System Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

- Introduction
- Conformance
- Environment Properties
- Types of Objects and how Objects are Named
- API Mapping

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

- Allow clients to traverse the file system namespace using JNDI's context interface.
- 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).

This document describes the features of the file system service provider and contains details of how JNDI is mapped to the file system.

## 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 `java.io.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.

## Environment Properties

The following JNDI environment properties are relevant to the file system service provider. See the JNDI documentation for a description of how properties are initialized using the environment properties, system properties, applet parameters, and resource files.

    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:

> >     env.put(Context.INITIAL_CONTEXT_FACTORY,
> >         "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:

> >     env.put(Context.INITIAL_CONTEXT_FACTORY,
> >         "com.sun.jndi.fscontext.RefFSContextFactory");

> This environment property must be set if you are using the file system provider for the initial context. The only exception is if you supply only URLs to the initial context, in which case, you don't need to specify this property. See the Types of Objects and how Objects are Named section for details.

    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 property is not set, it defaults to the root of the local file system.

    java.naming.factory.state

> A colon-separated list of the fully qualified class names of state factory classes used to get an object's state for storing given the object itself. You can use this mechanism to transform an object into forms that the files system service provider supports. The file system service provider supports storing `Reference` and `Referenceable` objects. See `javax.naming.spi.NamingManager.getStateToBind()` for details.

    java.naming.factory.object

> A colon-separated list of the fully qualified class names of object factory classes for transforming objects read from the file system. You can use this mechanism to transform an object into forms expected by the application. See `javax.naming.spi.NamingManager.getObjectInstance()` for details.

## Types of Objects and how Objects are Named

Names

Contexts and objects are named using the filename syntax of the local or networked file system of the underlying platform. When naming objects, use either the `javax.naming.Name` class or construct strings with `java.io.File.separator`. This will ensure that the code will work on any file system, regardless of its filename syntax.

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 is the directory specified in the `java.naming.provider.url` property. 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:

- The initial factory is `RefFSContextFactory` (not `FSContextFactory`)
- The object is of type `java.naming.Reference` or implements `java.naming.Referenceable`

Here is an example of how to store a `Referenceable` object:

>     class MyObject implements Referenceable {
>     	...
>     }
>     MyObject obj = new MyObject();
>     initCtx.bind("metamorphosis/myBoundObject", obj);

To retrieve an object, the object factory listed in the `Reference` must be made available, for example, in the classpath of the application.

>     MyObject obj = initCtx.lookup("metamorphosis/myBoundObject");

URLS

You can supply a "file" URL to the initial context. For example,

>     InitialContext ictx = new InitialContext();
>     Object helloRef = ictx.lookup("file:/c:/tmp/somefile");

## API Mapping

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 a `Reference` or implement the `Referenceable` interface. 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`. `NamingManager.getStateToBind()` is called to allow the object to be transformed into `Reference` and `Referenceable` objects so that it can be bound.

    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.

    getNameInNamespace()

> Returns the absolute filename of the directory in the file system.

    getNameParser()

> Returns a name parser for file system names.

    lookup()
    lookupLink()

> Returns the object named relative to the context. The object is of type `Context` if the name refers to a directory, a `File` if the name refers to a file), or of an arbitrary type if that was previously bound in the file system. `NamingManager.getObjectInstance()` is called before the object is returned in case the application or user has supplied object factories.

    list()
    listBindings()

> Lists the contents of the named context (i.e. directory). The contents will consist of other contexts (directories), files, and objects previously bound to the named context. `NamingManager.getObjectInstance()` is called on the objects returned in `listBindings` before they are returned in case the application or user has supplied object factories.

    removeFromEnvironment()

> Removes the named property from the context's environment.

    rebind()

> Binds the given object to the file system, overwriting any previous object. If an object was previously bound to the given name, it is overwritten. The supplied object must be a `Reference` or implement the `Referenceable` interface. Like `bind()`, `NamingManager.getStateToBind()` is called to allow the object to be transformed into `Reference` and `Referenceable` objects.

    rename()

> Renames an object. Renaming a context or file results in a corresponding change to its name in the file system. Arbitrary objects can be renamed too.

    unbind()

> Removes the given name and object from the file system.

Copyright © 1999 Sun Microsystems, Inc., All Rights Reserved.