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=jndidocs
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=jndidocs 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 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=jndidocs \
      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=jndidocs>

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=jndidocs"
java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"

For the JNDI to access an applet's parameters, 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).