User: stark
Date: 01/03/14 18:35:43
Modified: src/docs howtojndi_external.xml
Log:
Updated to document the RemoteAccess attribute.
Revision Changes Path
1.2 +96 -111 manual/src/docs/howtojndi_external.xml
Index: howtojndi_external.xml
===================================================================
RCS file: /products/cvs/ejboss/manual/src/docs/howtojndi_external.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howtojndi_external.xml 2001/03/01 22:27:36 1.1
+++ howtojndi_external.xml 2001/03/15 02:35:43 1.2
@@ -1,142 +1,127 @@
-<section><title>External JNDI Configuration and JNDI Viewing</title>
- <para>
- Author:
- <author><firstname>Scott</firstname><surname>Stark</surname></author>
- <email>[EMAIL PROTECTED]</email>
- </para>
-
+<?xml version = "1.0" encoding = "UTF-8"?>
<section>
-<title>How To Use the JNDI ExternalContext and JNDIView MBeans</title>
-<para>The ExternalContext JNDI MBean allows one to federate external
+ <title>External JNDI Configuration and JNDI Viewing</title>
+ <para> Author:<author>
+ <firstname>Scott</firstname>
+ <surname>Stark</surname>
+ </author>
+ <email>[EMAIL PROTECTED]</email>
+ </para>
+ <section>
+ <title>The JNDI ExternalContext and JNDIView MBeans</title>
+ <para>The ExternalContext JNDI MBean allows one to federate external
JNDI contexts into the JBoss server JNDI namespace. This allows one
to incorporate LDAP servers, Filesystem directories, DNS servers, etc.
-even if the JNDI providers root context is not Serializable.
-</para>
-
-<para>
-The JNDIView MBean allows one to view the JNDI namespace tree as it exists
-in the JBoss server using the JMX agent view interface.
-</para>
-</section>
-
-<section>
- <title>Preparation of the ExternalContext MBean</title>
-<para>
-First you have to add the ExternalContext service to the jboss.jcml
+even if the JNDI providers root context is not Serializable. The federation can be
made available to remote client in some circumstances.</para>
+ <para>The JNDIView MBean allows one to view the JNDI namespace tree as
it exists
+in the JBoss server using the JMX agent view interface.</para>
+ </section>
+ <section>
+ <title>Preparation of the ExternalContext MBean</title>
+ <para>First you have to add the ExternalContext service to the
jboss.jcml
in order to load the service. The folloing jboss.jcml fragment shows
-the setup for an LDAP server and a local filesystem directory:
-
-<literallayout><![CDATA[
+the setup for an LDAP server and a local filesystem
directory:<literallayout><![CDATA[
<!-- Bind a remote LDAP server -->
-<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext/ldap/dscape" >
+<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext,jndiName=external/ldap/dscape" >
<attribute name="JndiName">external/ldap/dscape</attribute>
<attribute name="Properties">dscape.ldap</attribute>
<attribute
name="InitialContext">javax.naming.ldap.InitialLdapContext</attribute>
+ <attribute name="RemoteAccess">true</attribute>
</mbean>
<!-- Bind the /Scott filesystem directory -->
-<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext/fs/Scott" >
+<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext,jndiName=external/fs/Scott" >
<attribute name="JndiName">external/fs/Scott</attribute>
<attribute name="Properties">scott_fs.props</attribute>
<attribute name="InitialContext">javax.naming.InitialContext</attribute>
</mbean>
-]]>
-</literallayout>
-where:
-<itemizedlist>
- <listitem><simpara>code="org.jboss.naming.ExternalContext" specifies the class
that impliments the
-external context mbean.
-</simpara></listitem>
- <listitem><simpara>name="DefaultDomain:service=ExternalContext/ldap/dscape"
assigns the name of the
-mbean. This is using a convention that appends the unique portion of the jndi
-name to the JMX name so that multiple external context mbeans are easily
-distiguishable in the JMX agent view.
-</simpara></listitem>
- <listitem><simpara>JndiName is the name with which the external context is
bound into the JBoss JNDI namespace
-</simpara></listitem>
- <listitem><simpara>Properties is URL string to a jndi.properties style of file
for the JNDI provider whose
-context is to be created. This can be any url for which there is a handler or a
simple
+
+]]></literallayout>where:<itemizedlist>
+ <listitem>
+
<simpara>code="org.jboss.naming.ExternalContext" specifies the class that impliments
the
+external context mbean.</simpara>
+ </listitem>
+ <listitem>
+
<simpara>name="DefaultDomain:service=ExternalContext,jndiName=external/ldap/dscape"
+assigns the name of the mbean. This is using a convention that sets the service
+property of the key to ExternalContext and adds a jndiName property that equals
+the mbean JndiName attribute. This allows multiple ExternalContext mbeans to
+easily be located and differentiated.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>JndiName is the name with which the
external context is bound into the JBoss JNDI namespace</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Properties is URL string to a
jndi.properties style of file for the JNDI provider
+whose context is to be created. This can be any url for which there is a handler or
a simple
string in which case it is treated as a resource that can be loaded via the current
-thread's context class loader.
-</simpara></listitem>
- <listitem><simpara>InitialContext is the class name of the InitialContext
class to create. Should be one
+thread's context class loader.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>InitialContext is the class name of
the InitialContext class to create. Should be one
of javax.naming.InitialContext, javax.naming.directory.InitialDirContext, or
javax.naming.ldap.InitialLdapContext. In the case of the InitialLdapContext, a null
-Controls array is used.
-</simpara></listitem>
-</itemizedlist>
-</para>
-<para>
-This example is binding an external LDAP context into the JBoss JNDI namespace under
-the name "external/ldap/dscape". An example dscape.ldap properties file is:
-<literallayout>
-java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
+Controls array is used. If this property is not given it defaults to
+javax.naming.InitialContext</simpara>
+ </listitem>
+ <listitem>
+ <simpara>RemoteAccess is a boolean flag
indicating if the external InitialContext should be
+bound using a Serializable form that allows a remote client to create the external
+InitialContext. When a remote client looks up the external context via the JBoss
JNDI
+InitialContext they effectively create an instance of the external InitialContext
using
+the same env properties passed to the ExternalContext mbean. This will only work if
+the client could do a 'new InitialContext(env)' remotely. This requires that the
provider
+url makes sense. For the LDAP example this should work. For the FileSystem example
this
+most likely won't work unless the FileSystem path refers to a common network path.
+If this property is not given it defaults to false.</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>This example is binding an external LDAP context into the JBoss
JNDI namespace under
+the name "external/ldap/dscape". An example dscape.ldap properties file
is:<literallayout>java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://ldaphost.displayscape.com:389/o=displayscape.com
java.naming.security.principal=cn=Directory Manager
java.naming.security.authentication=simple
-java.naming.security.credentials=secret
-</literallayout>
-With this mbean loaded, you can access the external LDAP context located at
+java.naming.security.credentials=secret</literallayout>With this mbean loaded, you
can access the external LDAP context located at
"ldap://ldaphost.displayscape.com:389/o=displayscape.com"
-from within the JBoss VM using the following code fragment:
-<programlisting>
-InitialContext iniCtx = new InitialContext();
+from within the JBoss VM using the following code
fragment:<programlisting>InitialContext iniCtx = new InitialContext();
Context ldapCtx = iniCtx.lookup("external/ldap/dscape");
-...
-</programlisting>
-Using the same code fragment outside of the JBoss server VM will not work
-because the ObjectFactory used to handle the Reference to the LDAP context
-is designed to only work within a single VM. Future versions of the ExternalContext
-mbean will provide support for enabling remote access to the federated context if
-desired.
-</para>
-</section>
-
-<section>
-<title>Preparation of the JNDIView MBean</title>
-<para>
-All that is required to use the JNDIView service is to add it to jboss.jcml
-The mbean tag looks like this:
-<literallayout><![CDATA[
+...</programlisting>Using the same code fragment outside of the JBoss server VM
will work in this case
+because the RemoteAccess property was set to true. If it was set to false it would
+not work because the remote client would receive a Reference object with an
ObjectFactory
+that would not be able to recreate the external IntialContext.</para>
+ </section>
+ <section>
+ <title>Preparation of the JNDIView MBean</title>
+ <para>All that is required to use the JNDIView service is to add it to
jboss.jcml
+The mbean tag looks like this:<literallayout><![CDATA[
<mbean code="org.jboss.naming.JNDIView" name="DefaultDomain:service=JNDIView" >
</mbean>
-]]>
-</literallayout>
-There are no configurable attributes. This simply loads the mbean into the JBoss
-server VM so that it can be used via the JMX MBean View.
-</para>
-</section>
-
-<section>
-<title>Using the JNDIView MBean</title>
-<para>
-To view the JBoss JNDI namespace using the JNDIView mbean, you connect to the
-JMX Agent View using the http interface. The default settings put this at
-<ulink url="http://localhost:8082/">http://localhost:8082/</ulink>. On this
+]]></literallayout>There are no configurable attributes. This simply loads the
mbean into the JBoss
+server VM so that it can be used via the JMX MBean View.</para>
+ </section>
+ <section>
+ <title>Using the JNDIView MBean</title>
+ <para>To view the JBoss JNDI namespace using the JNDIView mbean, you
connect to the
+JMX Agent View using the http interface. The default settings put this at<ulink url
= "http://localhost:8082/">http://localhost:8082/</ulink>. On this
page you will see a section that lists the registered MBeans by domain. It
-should look something like this:
-
-<screen>
- <inlinegraphic fileref="images/agent_view.jpg" />
-</screen>
-</para>
-<para>
-This is showing two registered ExternalContext mbeans(ExternalContext/fs/Scott[a
filesystem] and
+should look something like this:<screen>
+ <inlinegraphic fileref = "images/agent_view.jpg"/>
+ </screen>
+ </para>
+ <para>This is showing two registered ExternalContext
mbeans(ExternalContext/fs/Scott[a filesystem] and
ExternalContext/ldap/dscape[an ldap server]) mbeans as well as the JNDIView
mbean. Selecting the service=JNDIView link takes you to the JNDIView MBean
-View which will have a list of MBean operations section similar to:
-<screen>
- <inlinegraphic fileref="images/jndiview_ops.jpg" />
-</screen>
-</para>
-<para>
-Invoking the list operation creates a dump of the JBoss JNDI namespace that
+View which will have a list of MBean operations section similar to:<screen>
+ <inlinegraphic fileref = "images/jndiview_ops.jpg"/>
+ </screen>
+ </para>
+ <para>Invoking the list operation creates a dump of the JBoss JNDI
namespace that
includes the federated external contexts. As an example, this is the dump
with the filesystem and ldap contexts. The following image displays the
start of the global JNDI namespace and includes the external/fs/Scott
-local filesystem directory contents.
-<screen>
- <inlinegraphic fileref="images/jndiview_list.jpg" />
-</screen>
-</para>
-</section>
+local filesystem directory contents.<screen>
+ <inlinegraphic fileref = "images/jndiview_list.jpg"/>
+ </screen>
+ </para>
+ </section>
</section>
