This plug-in implements JNDI exploring capability for Eclipse version 2. Get acquainted with this plug-in's capabilities by viewing an annotated screenshot. Please read the legal requirements before using this software.
The Java Naming and Directory Interface™ (JNDI) is a standard extension to the Java™ platform, providing Java applications with a unified interface to multiple naming and directory services in the enterprise. As part of the Java Enterprise API set, JNDI enables seamless connectivity to heterogeneous enterprise naming and directory services. Thus a JNDI client such as this plug-in is able to view and edit LDAP directories, Corba or RMI registries, and even the Windows registry!
Because JNDI gives uniform access to many different types of resources (e.g. DNS names, RMI objects, LDAP directories, etc.), it defines its own terminology to manipulate them. The nodes in a JNDI namespace are known as contexts. The root node is known as the initial context. Initial contexts are created by initial context factories.
JNDI follows the well-known software design pattern Bridge: abstract JNDI classes offer homogeneous access to many different naming services, while delegating the exact details of accessing a specific datastore to "provider implementations". The JNDI architecture consists of an API and a service provider interface (SPI). This plug-in uses the JNDI API to access a variety of naming and directory services. The SPI enables a variety of naming and directory services to be plugged in transparently, thereby allowing the plug-in using the JNDI API to access their services. See the following figure. (The same model is used in JDBC.)
This plug-in does not come with any JNDI service providers. It doesn't really need to, because the most common providers are bundled with the JDK 1.3 and above. Soem additional JNDI service providers can downloaded from the JNDI product homepage; some are bundled with third-party products (e.g. J2EE application servers).
What kind of naming/directory service you access is selected by choosing
an appropriate initial context factory -- a concrete class that implements the
InitialContextFactory interface. Which service you access is
selected by creating a provider URL.
The combination of a initial context factory and the objects implementing
the provider URL is known as a JNDI service provider, and gives access to
a specific naming service.
E.g. to browse a local RMI registry, one would typically use:
| Initial Context Factory | com.sun.jndi.rmi.registry.RegistryContextFactory
|
|---|---|
| Provider URL | rmi://localhost
|
Or, to browse a fictitious LDAP server hosted at ldap.example.com:
| Initial Context Factory | com.sun.jndi.ldap.LdapCtxFactory
|
|---|---|
| Provider URL | ldap://ldap.example.com/dc=example,dc=com
|
But let us now move on to how to actually use this plug-in.
See the INSTALL document in this directory.
Start up Eclipse, open the "Window" menu, and select "Show View". Select "Other...", expand the "Java" node in the window that opens, and select the "JNDI Explorer" view.
The view opens up empty. To populate the view, you want to add a new initial context. To do so, either click the icon that looks like three little "plus" signs in the view's window bar, or select "Add New Initial Context" in the view menu. A dialog opens, and is shown below.
The first field shows a list of pre-configured JNDI services known to work with this plug-in. Selecting a service from the menu populates the other fields in the dialog. Since this plug-in does not include any JNDI libraries, not all the choices in that menu may be usable; it is up to you to add the corresponding JNDI libraries to your project.
Note:
The services listed in the menu are not necessarily accessible from your environment.
If you attempt to use one and get a ClassNotFoundException error, then the
initial context factory class cannot be found in your workspace.
To solve this problem, you must locate the library (JAR file) containing
the initial context factory, and add it to your workspace. Typically you would so
by adding the JAR to the build path of your project.
If the service you wish to explore isn't listed in the menu, click the "Browse..." button to
choose from a list of classes implementing the InitialContextFactory interface.
(See below.) Any of those classes can be used to create a new initial context.
Note: As mentioned above, the initial context factory classes are found in the workspace. To be usable by the JNDI Explorer plug-in, they must be referenced in the build path (the classpath) of your project.
Once you have selected a initial context factory, you must enter a provider URL, or edit the default value provided. The exact syntax of the provider URL depends on the service provider; it usually starts with the protocol used to access the service provider, followed by the name of the machine hosting the service, followed by one or more specifiers. See the "Introduction" section for some examples of provider URLs.
The naming/directory service you wish to access may require you to authenticate using a username and password. Use the "Username" and "Password" fields to do so. Note that the password value is only used to access the service, and is never saved by the plug-in.
Finally, some JNDI service providers require additional environment properties for the successful initialization of the initial context factory. They can be entered in the multi-line field at the bottom of the dialog. Defaults are provided for the most common service providers.
Once you have filled out the dialog, click OK to create the initial context. Note that all the values entered in this dialog are persisted (at the exception of the password field). The next time you open this dialog to configure another initial context, the values you entered will still be there.
Note:
The most common error at this point is a ClassNotFoundException
error. This means the initial context factory class could not be found in your workspace.
To solve this error, locate the JAR for the JNDI service provider you wish to use, and add it to your
project: right-click and the project icon and select "Properties", then "Java Build Path".
The "Libraries" tab allows you to add external JARs.
Once the initial context is created, it shows up in the view. You can use the hierarchical explorer to navigate around the context. Experiment with the navigation controls in the view menubar; their icons look like a little house, and left/right arrows.
Right-click on a tree item to show some possible actions that can be applied to the context, such as creating or deleting. Other actions include removing the context from the view, or refreshing the explorer.
Directory services such as LDAP store attributes in addition to names and objects bound to those names. Attributes of a context are displayed in the Properties view. To open the Properties view, go to Window/Show View/Other.../Basic and select "Properties".
The Properties view displays the properties and attributes of the context currently selected in the JNDI Explorer. Some context properties, listed below, are read-only and cannot be edited. Others can be clicked and edited in the properties view.
| Property Name | Value | Editable |
|---|---|---|
name
| the name of this object | yes |
boundObject
| a string representation of the object bound to this item | no |
className
| the class name of the bound object | no |
url
| a URL identifying this item, only useful for informative purposes | no |
Additional properties (known as context attributes) are dependent on the directory service
used. E.g. the screenshot above shows the attributes of an LDAP object. The sn attribute
is being edited.
The changes made to an attribute are immediately saved to the naming/directory service. Note that this may fail if the service is accessed without sufficient permission.