jndi-cos.html

JavaJNDI examples of J[2]EE

   </dl>
</ol>
   <p>

   If the properties employed in steps (a), (b) and (c) contain
   no relevant information for initializing the ORB, the Java IDL 
   implementation's defaults are used. Typically that means port 900 on
   the local host for an application, and port 900 on the applet host for 
   an applet are used.

   Note that when the ORB is initialized using <tt>ORB.init()</tt>, its
   arguments are checked in the following order: (from 
   <tt>org.omg.CORBA.ORB</tt> javadoc)

<ol>
    <li> check in <tt>Applet</tt> parameter or application string array,
         if any 
    <li> check in properties parameter, if any 
    <li> check in the <tt>System</tt> properties (currently applications
         only) 
    <li> fall back on a hardcoded default behavior (use the Java IDL implementation) 
</ol>
<hr>
<p>
<A NAME="ROOT">
<H2>Root Naming Context Initialization</H2>
<p>
The root naming context is initialized either using the
<a href=#URLPROP><tt>java.naming.provider.url</tt></a> property or by a
<tt>resolve_initial_references()</tt>
call on the ORB. If the <tt>java.naming.provider.url</tt> property is set
but contains neither an "iiop" or "iiopname" URL, it is assumed to contain
a stringified IOR or a URL containing the location of a stringified
IOR. The stringified IOR is used to obtain the root naming context.
The stringified IOR must be that of a CORBA object of type
<tt>CosNaming::NamingContext</tt>.
<p>
If the <tt>java.naming.provider.url</tt> has not been set or does not
contain a stringified IOR or its location, the root naming context is
obtained by invoking the following method on the ORB:
<p>
<pre>
        orb.resolve_initial_references("NameService");
</pre>

<hr>
<p>
<A NAME="URL">
<H2>Names and URLs</H2>
<p>


<b><tt>String</tt> Names</b>

<p>
<tt>String</tt> names accepted by the <tt>java.naming.Context</tt> methods
are 
<a href="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/CompositeName.html">JNDI composite names</a>
in which each component is the stringified form
of a <tt>CosNaming::NameComponent</tt>. 

<p>
A <tt>CosNaming::Name</tt> 
contains a sequence of <tt>CosNaming::NameComponent</tt>. The stringified
form of a component is the concatenation of the component's id, the kind
separator character ('.'), and the component's kind.  The occurrence of
any meta characters ('.', '/', or '\') in either the id or kind is escaped
using the escape character ('\').
The stringified form of a <tt>CosNaming::Name</tt> is defined in Section
4.5 of the 
<a href="ftp://ftp.omg.org/pub/docs/orbos/98-10-11.pdf">INS specification</a>.
<p>
The 
<a href="http://java.sun.com/products/jndi/1.2/javadoc/javax/naming/CompositeName.html">JNDI composite name syntax</a>
is very similar to, but not identical
to, the INS syntax. There are minor differences with respect to the 
treatment of escape and quote characters. If you are want to use names
with the precise INS syntax, you should use the overloads that accept a
<tt>Name</tt> argument instead of a <tt>String</tt> argument. The 
<tt>Name</tt> argument should be a value returned by
<tt>nameParser.parse()</tt>, where <tt>nameParser</tt> is a value obtained
from the COS naming service provider. See the <a href="#PARSE">Name
Parsing</a> section.
<p>

<b>URL String Names</b>

<p>

The URL form of a <tt>CosNaming::Name</tt> is defined in the INS
specification.
<p>
<blockquote>
<tt>
	iiopname://[&lt;addr_list>][/&lt;cosnaming name>]
</tt>
</blockquote>
<p>
where <tt>addr_list</tt> specifies a list of host/port pairs.
If the port is not specified, it defaults to 9999. <tt>&lt;cosnaming
name></tt> is the stringified form of an INS name (see 
<a href="#PARSE">Name Parsing</a>).
<p>
For backward compatibility with an older INS specification, the following
URL is also supported

<p>
<blockquote>
<tt>
	iiop://&lt;host>[:&lt;port>][/&lt;cosnaming name>]
</tt>
</blockquote>
<p>
If port is not supplied, it defaults to 900. <tt>&lt;cosnaming name></tt> 
is the stringified form of an INS name (see 
<a href="#PARSE">Name Parsing</a>).
<p>
When you supply the URL to the initial context in this way, the ORB
supplied to the initial context is ignored. In fact, the values of the
<tt>java.naming.factory.initial</tt> and <tt>java.naming.corba.orb</tt>
properties are ignored.
<p>
For example, the following code will contact the naming service running
on host 'server', at port '1900', and lookup the INS name "some/cos/name".
<p>
<blockquote>
<pre>
InitialContext ictx = new InitialContext();   
Object helloRef = ictx.lookup("iiopname://server:1900/some/cos/name");
</pre>
</blockquote>
<p>

<b>Name Objects</b>
<p>

The <tt>Name</tt> argument to a <tt>Context</tt> method is treated as a
sequence of strings, each representing a stringified
<tt>CosNaming::NameComponent</tt>.
<p>

<b><a name="PARSE">Name Parsing</a></b>
<p>
The COS naming service provider supports names in the syntax specified
in the INS specification. In short, the syntax is that components are
left-to-right slash ('/') separated and case-sensitive.  The id and
kind of each component are separated by the period character ('.').
<p>
Here is a code fragment that uses the name parser from the COS naming
service provider to eventually do a lookup using an INS name.
<p>
<blockquote>
<pre>
String insName = ...;
InitialContext ctx = new InitialContext(env);   // env contains init properties
NameParser parser = ctx.getNameParser("");      // parser for INS names
Name name = parser.parse(insName);              // get parsed INS name
Object obj = ctx.lookup(name);                  // do lookup
</pre>
</blockquote>

<hr>
<p>


<A NAME="API">
<H2>API Mapping</H2>
<p>

The COS name server supports only naming operations.  The COS naming
service provider maps the <tt>javax.naming.Context</tt> methods to use the
appropriate COS Naming calls.


<b><pre>addToEnvironment()</pre></b>

    <blockquote>
    Records change to environment property but does not reinitialize
    ORB.
    </blockquote>

<b><pre>bind()</pre></b>

    <blockquote>
    If the object being bound is an
    <tt>org.omg.CosNaming.NamingContext</tt>,
    <tt>CosNaming::NamingContext.bind_context</tt> is used. If it is an 
    <tt>org.omg.CORBA.Object</tt>, <tt>CosNaming::NamingContext.bind</tt> is used.
    Binding of any other types of object is not supported.
    <p>
    Before the bind is performed on the naming server, the COS naming
    service provider uses <tt>javax.naming.spi.NamingManager.getStateToBind()</tt>
    to allow the object to be transformed into a 
    <tt>org.omg.CORBA.Object</tt>.
    By default, a state factory that transforms an object implementing
    the <tt>java.rmi.Remote</tt> interface to an <tt>org.omg.CORBA.Object</tt>
    is supplied and used. 
    This factory uses the <tt>javax.rmi.CORBA</tt> package.
    You can supply additional state factories
    to transform objects into CORBA objects for binding.
    </blockquote>
    
<b><pre>close()</pre></b>

    <blockquote>
    Releases any internal data structures used.
    </blockquote>

<b><pre>composeName()</pre></b>
    <blockquote>
    Concatenates the supplied name to the prefix.
    </blockquote>

<b><pre>createSubcontext()</pre></b>
    <blockquote>
    Uses <tt>CosNaming::NamingContext.bind_new_context</tt> to create and bind
    a new context.
    </blockquote>

<b><pre>destroySubcontext()</pre></b>
    <blockquote>
    Uses <tt>CosNaming::NamingContext.destroy</tt> to destory the named context.
    Then uses <tt>CosNaming::NamingContext.unbind</tt> to remove the binding.
    </blockquote>

<b><pre>getEnvironment()</pre></b>
    <blockquote>
    Returns the environment of this context.
    </blockquote>

<b><pre>getNameInNamespace()</pre></b>
    <blockquote>
    Returns the INS name of this context relative to the root naming context.
    </blockquote>

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

<b><pre>lookup()
lookupLink()</pre></b>
    <blockquote>
    Uses <tt>CosNaming::NamingContext.resolve</tt> to lookup the name.
    It returns a CORBA object reference except when the reference is
    that of a <tt>CosNaming::NamingContext</tt>, in which case a 
    <tt>Context</tt> object is returned instead.  
    <tt>NamingManager.getObjectInstance()</tt>
    is called before the object is returned in case the application
    or user has supplied object factories.
    </blockquote>

<b><pre>
list()
listBindings()</pre></b>
    <blockquote>
    Uses <tt>CosNaming::NamingContext.resolve</tt> to get the object reference 
    for the context,
    and then uses <tt>CosNaming::BindingIterator</tt> and helper classes to iterate
    through the context. 
    The objects bound to the names are obtained by calling
    <tt>CosNaming::NamingContext.resolve</tt> on them. 
    <tt>NamingManager.getObjectInstance()</tt>
    is called before the object is returned in case the application
    or user has supplied object factories.
    </blockquote>

<b><pre>removeFromEnvironment()</pre></b>
    <blockquote>
    Removes the specified property from the environment but
    does not otherwise update the context.
    </blockquote>

<b><pre>rebind()</pre></b>
    <blockquote>
    If the object being bound is an
    <tt>org.omg.CosNaming.NamingContext</tt>,
    <tt>CosNaming::NamingContext.rebind_context</tt> is used. If it is an 
    <tt>org.omg.CORBA.Object</tt>, <tt>CosNaming::NamingContext.rebind</tt> is
    used. See <tt>bind()</tt> for details on the use of state factories
    to transform the argument into an <tt>org.omg.CORBA.Object</tt>.
    </blockquote>

<b><pre>rename()</pre></b>
    <blockquote>
    This method is implemented using <tt>bind()</tt> followed by 
    <tt>unbind()</tt>.  It is not atomic.
    </blockquote>

<b><pre>unbind()</pre></b>
    <blockquote>
    Uses <tt>CosNaming::NamingContext.unbind</tt> to unbind the object.
    </blockquote>

<hr>
<p>
<A NAME="CORBA">
<H2>Converting CORBA Programs to use JNDI</H2>
<p>

This section explains how to modify your Java IDL program to use JNDI. 
The explanation uses the Java IDL sample programs
<tt>helloClient.java</tt> and <tt>helloServer.java</tt>.

<ol>
<li>Generate the stubs from the IDL file.
<p>
<blockquote>
<pre>
# idltojava -fclient -fserver hello.idl
</pre>
</blockquote>
<p>
This creates the client (<tt>helloClient.java</tt>) and server
(<tt>helloServer.java</tt>) skeletons, and a directory containing common code
(e.g. <tt>HelloApp/*.java</tt>).
<p>
<li>Fill in the code for the client and server programs.
<p>
<li>Modify (or copy the client and server files) to use JNDI instead
of COS Naming directly.
<p>
<ul>
<li>Replace the import to use <tt>javax.naming.*;</tt>
<blockquote>
Delete:
<pre>
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
</pre>
Add:
<pre>
import javax.naming.*;
</pre>
</blockquote>

<li>Replace how you get the initial reference to "NameService"
with <tt>InitialContext</tt>, supplying the initial context
the ORB being used by the current application.

<blockquote>
Delete:
<pre>
org.omg.CORBA.Object objRef = 
   orb.resolve_initial_references("NameService");
NamingContext ncRef = NamingContextHelper.narrow(objRef);
</pre>
Add:
<pre>
Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
Context ic = new InitialContext(env);
</pre>
</blockquote>

<li>Replace the call to <tt>resolve()</tt> to use <tt>lookup()</tt>.

<blockquote> 
Delete:
<pre>
// resolve the Object Reference in Naming
NameComponent nc = new NameComponent("Hello", "");
NameComponent path[] = {nc};
hello helloRef = helloHelper.narrow(ncRef.resolve(path));
</pre>

Add:
<pre>
// resolve the Object Reference using JNDI
hello helloRef = 
helloHelper.narrow((org.omg.CORBA.Object)ic.lookup("Hello"));
</pre>
</blockquote>

</ol>
</ol>
<hr>
<p>
<A NAME="SEC">
<h2>Security Considerations</H2>
<p>

When a security manager has been installed, 
you must grant to the application using JNDI and the
COS naming service provider the following permissions:

<p>
<pre>permission java.net.SocketPermission "host[:port]", "connect";</pre>
<blockquote>
	For each host/port identified in the
        <tt>java.naming.factory.initial</tt> property, 
        in URL string names supplied to context methods, in ORB
	initialization parameters and properties, and in object references.
</blockquote>

<HR SIZE=3 NOSHADE WIDTH=100%>
<br><i>Copyright &copy; 1999 Sun Microsystems, Inc., All Rights Reserved.</i> 

   
</body>
</html>