jndi-dsml.html

J[2]EE JavaJNDI examples

    a new entry.
    </blockquote>
    
<b><pre>close()</pre></b>
    
    <blockquote>
    Releases any internal data structures used.
    </blockquote>
    
<b><pre>composeName()</pre></b>
    <blockquote>
    Concatenates two names.
    </blockquote>

<b><pre>createSubcontext()</pre></b>
    <blockquote>
    A new entry is created by using the attributes supplied.
    </blockquote>

<b><pre>destroySubcontext()</pre></b>
    <blockquote>
    The named entry is removed.
    </blockquote>
    
<b><pre>getAttributes()</pre></b>
    <blockquote>  
    Returns the <tt>dsml:attr</tt> and <tt>dsml:objectclass</tt>
    elements as attributes of the named entry.
    </blockquote>
    
<b><pre>getEnvironment()</pre></b>
    <blockquote>  
    Returns the environment properties associated with this context.
    </blockquote>

<b><pre>getNameInNamespace()</pre></b>
    <blockquote>
    Returns the distinguished name of this entry. 
    </blockquote>

<b><pre>getNameParser()</pre></b>
    <blockquote>
    Returns a name parser for parsing LDAP distinguished names.
    </blockquote>

<b><pre>getSchema()</pre></b>
    <blockquote>
    Returns the root of the schema tree.
    </blockquote>

<b><pre>getSchemaClassDefinition()</pre></b>
    <blockquote>
    Returns an immutable context that contains the class definitions of 
    the named entry.
    The context is empty if there is no schema data available for any
    of the entry's object classes.
    </blockquote>

<b><pre>lookup()
lookupLink()</pre></b>
    <blockquote>
    Returns the <tt>DirContext</tt> that represents the named entry.
    <tt>DirectoryManager.getObjectInstance()</tt> is invoked on the object
    before it is returned in case the application
    or user has supplied object factories.
    </blockquote>

<b><pre>
list()
listBindings()</pre></b>
    <blockquote>
    Returns a list of <tt>DirContext</tt> of the named entry.
    </blockquote>

<b><pre>modifyAttributes()</pre></b>
    <blockquote>
    Modifies the attributes of the named entry.
    </blockquote>

<b><pre>removeFromEnvironment()</pre></b>
    <blockquote>
    Environment properties can be removed via this method but such
    action does not affect the current context.
    </blockquote>
    
<b><pre>rebind()</pre></b>
    <blockquote>
    Operation not supported. Use <tt>createSubcontext()</tt> to create
    a new entry.
    </blockquote>
    
<b><pre>rename()</pre></b>
    <blockquote>
    The named entry is renamed.
    </blockquote>
    
<b><pre>search()</pre></b>
    <blockquote>
    All search methods are supported.
    <tt>DirectoryManager.getObjectInstance()</tt>
    is called when <tt>getObject()</tt> is invoked on the resulting enumeration
    in case the application or user has supplied object factories.
    </blockquote>
    
<b><pre>unbind()</pre></b>
    <blockquote>
    The named entry is removed.
    </blockquote>

<hr>
<p>
<A NAME="CONFIG">
<H2>LDAP URL Handler</H2>

<p>
As stated in the <a href=#PROP>Environment Properties</a> section,
the DSML v1 provider is configured by using the <tt>java.naming.provider.url</tt>
environment property. Directory data and schema data are extracted from the
DSML v1 document named by the URL in this property. Each URL scheme is handled
by a <tt>java.net.URLStreamHandler</tt>, 
responsible for opening a connection using
the network protocol named by the URL. When you are using Sun's "ldap"
<tt>URLStreamHandler</tt>, you can control how much schema data is returned
and pass JNDI environment properties to the underlying handler.

<h3>Returning Schema Entries</h3>

You can control how much schema data the "ldap" <tt>URLStreamHandler</tt>
emits and consequently control how many schema entries are
included in the DSML v1 document by using the System or environment property
<tt>sun.net.www.protocol.ldap.schema</tt>.
The setting of this property in the environment has precedence over 
the same System property setting.
Here are this property's possible settings.
The default is <tt>"none"</tt>.
<table>
<tr>
<td>
<tt>none</tt>
</td>
<td>Include no schema data
</td>
</tr>
<tr>
<td>
<tt>min</tt>
</td>
<td>Include schema definitions referenced by directory entries in document
</td>
</tr>
<tr>
<td>
<tt>all</tt>
</td>
<td>Include all schema definitions available from LDAP server
</td>
</tr>
</table>
Here is an example. To get only the schema definitions referenced, the command
line argument looks as follows.
<blockquote><pre>
# java -Dsun.net.www.protocol.ldap.schema=min ShowDsmlDocument ldap://localhost:389/o=JndiTutorial
</pre></blockquote>
<p>
See the <a href=jndi-dsml-ext.html#LDAPBP>Installation Instructions</a>
to see how to ensure that you have the latest version of the "ldap"
<tt>URLStreamHandler</tt>.


<h3>Passing Environment Properties</h3>

The DSML v1 provider reads the DSML v1 document by obtaining a
<tt>java.net.URLConnection</tt> from the 
<tt>java.net.URLStreamHandler</tt> corresponding to the URL named in
the <tt>java.naming.provider.url</tt> property.
Any environment properties supplied to the DSML v1 provider will be
passed to the underlying URL handler if the <tt>URLConnection</tt>
implements the <tt>com.sun.jndi.dsml.EnvContainer</tt> interface,
defined as follows.
<blockquote><pre>
public interface EnvContainer {
    void setEnvironment(java.util.Hashtable env);
}
</pre></blockquote>
For example, if <tt>java.naming.provider.url</tt> contains an "ldap" URL string
and you are using Sun's LDAP URL handler, you can authenticate to the
underlying JNDI/LDAP service provider by supplying the DSML v1 provider
with the <tt>Context.SECURITY_PRINCIPAL</tt> and 
<tt>Context.SECURITY_CREDENTIALS</tt>
properties. Here is an example.
<blockquote><pre>
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.dsml.DsmlCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost/o=JndiTutorial");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL,"cn=Directory Administrator, o=JndiTutorial");
env.put(Context.SECURITY_CREDENTIALS, "secret");

// Create the initial directory context
DirContext ctx = new InitialDirContext(env);
</pre></blockquote>
<tt>env</tt> will be used by both the DSML v1 provider and the underlying 
URL handler. In the case of Sun's LDAP URL handler, the security-related
properties will be used to authenticate the client to the LDAP server named in
<tt>Context.PROVIDER_URL</tt>.

<h3>Using the LDAP URL Handler Directly</h3>

The LDAP URL format is described in 
<a href="http://www.ietf.org/rfc/rfc2255.txt">RFC 2255</tt></a>.  
The DSML v1 provider contains an implementation of a
<tt>java.net.URLStreamHandler</tt> that reads the entry specified by
the URL and returns it as an DSML v1 document.
You can use this feature to read data from an LDAP server 
as DSML v1 formatted data directly (without any explicit JNDI calls).
<p>
Here is an example that reads the subtree rooted at the
<tt>o=jnditutorial</tt> entry from the LDAP server running on
port 389 of the local machine.
<blockquote>
<pre>
String url = "ldap://localhost:389/o=jnditutorial??sub";
// Optional: ask that associated schema definitions be returned
System.setProperty("sun.net.www.protocol.ldap.schema", "min");

// Open URL connection
URL u = new URL(url);
URLConnection conn = u.openConnection();

// Read entries in subtree as DSML v1 formatted document
BufferedReader in = new BufferedReader (
    new InputStreamReader(conn.getInputStream(), "UTF8"));
String str;
while((str = in.readLine()) != null) {
    System.out.println(str);
}
</pre>
</blockquote>
To pass credentials to be used by the "ldap" <tt>URLStreamHandler</tt>,
you would add the following code before invoking 
<tt>conn.getInputStream()</tt>.

<blockquote>
<pre>
...
URLConnection conn = u.openConnection();
if (conn instanceof com.sun.jndi.dsml.EnvContainer) {
    Hashtable env = new Hashtable();
    env.put(Context.SECURITY_PRINCIPAL, "cn=someone");
    env.put(Context.SECURITY_CREDENTIALS, "password");
    ((com.sun.jndi.dsml.EnvContainer)conn).setEnvironment(env);
}
InputStream in = conn.getInputStream();
...
</pre>
</blockquote>



<hr>
<p>
<A NAME="FED">
<H2>Federation</H2>
<p>
The DSML v1 service provider does not support federation.
        
<HR SIZE=3 NOSHADE WIDTH=100%>
<br><i>Copyright &copy; 2002 Sun Microsystems, Inc., All Rights Reserved.</i> 

</body>
</html>