| Environment Properties

## Specifying Environment Properties

> You can specify environment properties to the JNDI by using the environment parameter to the `InitialContext` constructor and application resource files. Several JNDI standard environment properties could be specified also by using system properties and applet parameters, as described later in this section.

> #### Application Resource Files

> To simplify the task of setting up the environment required by a JNDI application, you may distribute application resource files along with application components and service providers. An application resource file has the name `jndi.properties`. It contains a list of key/value pairs presented in the properties file format (see `java.util.Properties`). The key is the name of the property (for example, `java.naming.factory.object`) and the value is a string in the format defined for that property.

> Here is an example of an application resource file.

> >     java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
> >     java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
> >     java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
> >     java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
> >     java.naming.provider.url=ldap://localhost:389/o=jnditutorial
> >     com.sun.jndi.ldap.netscape.schemaBugs=true

> Notice that no restrictions apply regarding the type of environment property that you can have in this file.

> The JNDI automatically reads the application resource files from all components in the applications' classpaths and JAVA_HOME`/lib/jndi.properties`, where JAVA_HOME is the file directory that contains your JRE (Java Runtime Environment). The JNDI then makes the properties from these files available to the service providers and other components that need to use them. Therefore these files should be considered world-readable and should not contain sensitive information, such as clear-text passwords.

> > Note: Except for JAVA_HOME`/lib/jndi.properties`, application resource files are supported only when you use the Java 2 platform. If you use the JDK 1.1 software, then you can see only JAVA_HOME`/lib/jndi.properties`.

> For example, following is a program that lists a context without specifying any environment properties in the `InitialContext` constructor.

> >     InitialContext ctx = new InitialContext();
> >     NamingEnumeration enum = ctx.list("");

> If you run this program with the `jndi.properties` file shown previously, then it will list the contents of the `o=jnditutorial` entry on the specified LDAP server.

> The use of application resource files to specify any JNDI environment properties allows the JNDI to be configured with minimal programmatic setup. By using the JAVA_HOME`/lib/jndi.properties` file, you can also configure the JNDI for all applications and applets that use the same Java interpreter.

> If you use application resource files, then you must remember to grant your applet or application permission to read all of the application resource files.

> #### System Properties

> A system property is a key/value pair that the Java runtime defines to describe the user, system environment, and Java system. The runtime defines and uses a set of default system properties. Other properties can be made available to a Java program via the `-D` command line option to the Java interpreter. For example, running the interpreter as follows

> >     # java -Dmyenviron=abc Main

> adds the property `myenviron` with the value `abc` to the list of system properties visible to the program `Main`. The `java.lang.System` class contains static methods for reading and updating system properties. The ability to read or update any system property is controlled by the security policy of the Java runtime system.

> The JNDI reads the following standard JNDI properties from the system properties:

> >     java.naming.factory.initial
> >     java.naming.factory.object
> >     java.naming.factory.state
> >     java.naming.factory.control
> >     java.naming.factory.url.pkgs
> >     java.naming.provider.url
> >     java.naming.dns.url

> When set as system properties, these environment properties affect the contexts of all applications or applets (if the applet is allowed permission to read these properties).

> Using the same program in the previous application resource file example, specify the initial context factory to use by giving the initial context to use on the command line. Here are two examples.

> >     # java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
> >           -Djava.naming.provider.url=ldap://localhost:389/o=jnditutorial \
> >           List
> >     # java -Djava.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory \
> >           -Djava.naming.provider.url=file:/tmp \
> >           List

> The first example uses LDAP, and the second one uses the file system.

> The use of system properties to specify standard JNDI environment properties allows the JNDI to be configured with minimal programmatic setup. However, they are probably convenient to use only from scripts. This is because items with long property names must be specified on the command line. Also, applets generally do not have permission to read arbitrary system properties and must be explicitly granted permission to do so.

> #### Applet Parameters

> You can pass parameters to an applet by using simple key/value pairs. They are specified in the HTML file that references the applet. How you specify them depends on the applet context. For example, if the applet is referenced from an `applet`, then you specify the parameters by using the `param` tag. Here is an example.

> >     <param
> >     name=java.naming.factory.initial
> >     value=com.sun.jndi.ldap.LdapCtxFactory>

> >     <param
> >     name=java.naming.provider.url
> >     value=ldap://localhost:389/o=jnditutorial>

> If the applet is referenced from the Java Plug-in, then you specify its parameters by using key/value pairs. Here is an example.

> >     java.naming.provider.url="ldap://localhost:389/o=jnditutorial"
> >     java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"

> For the JNDI to access an applet's parameters, you must set the `Context.APPLET` (`"java.naming.applet"`) environment property. The JNDI reads the following standard JNDI properties from the applet parameters:

> >     java.naming.factory.initial
> >     java.naming.factory.object
> >     java.naming.factory.state
> >     java.naming.factory.control
> >     java.naming.factory.url.pkgs
> >     java.naming.provider.url
> >     java.naming.dns.url

> Here is an example that adds a single property (`"java.naming.applet"`) to the environment.

> >     // Put this applet instance into the environment
> >     Hashtable env = new Hashtable();
> >     env.put(Context.APPLET, this);

> >     // Pass the environment to the initial context constructor
> >     Context ctx = new InitialContext(env);

> >     // List the objects
> >     NamingEnumeration enum = ctx.list(target);
> >     while (enum.hasMore()) {
> >          out.println(enum.next());
> >     }
> >     ctx.close();

> The JNDI then obtains the necessary environment properties from the applet parameters (shown previously).

> This use of applet parameters to specify standard JNDI environment properties allows the JNDI to be configured in the same way that an applet typically performs configuration for other subsystems or components. System properties and application resource files are not good mechanisms for applets to depend on. This is because applets typically cannot read system properties or arbitrary files (including `jndi.properties`).

| Environment Properties