User: stark
Date: 01/03/01 14:27:37
Modified: src/docs jbossdocs.xml
Added: src/docs howtojndi_external.xml
Log:
Ported the JNDIView and ExternalContext mbean html docs
Revision Changes Path
1.4 +2 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /products/cvs/ejboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- jbossdocs.xml 2001/03/01 21:58:24 1.3
+++ jbossdocs.xml 2001/03/01 22:27:36 1.4
@@ -18,6 +18,7 @@
<!ENTITY howtojbuilderdebug.xml SYSTEM "howtojbuilderdebug.xml">
<!ENTITY howtoejx.xml SYSTEM "howtoejx.xml">
<!ENTITY howtojca.xml SYSTEM "howtojca.xml">
+<!ENTITY howtojndi_external.xml SYSTEM "howtojndi_external.xml">
<!ENTITY basicconfiguration.xml SYSTEM "basicconfiguration.xml">
<!ENTITY howtomdb.xml SYSTEM "howtomdb.xml">
]>
@@ -52,6 +53,7 @@
&howtojbuilderdebug.xml;
&howtoejx.xml;
&howtojca.xml;
+&howtojndi_external.xml;
</chapter>
</book>
1.1 manual/src/docs/howtojndi_external.xml
Index: howtojndi_external.xml
===================================================================
<section><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>How To Use 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
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[
<!-- Bind a remote LDAP server -->
<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext/ldap/dscape" >
<attribute name="JndiName">external/ldap/dscape</attribute>
<attribute name="Properties">dscape.ldap</attribute>
<attribute name="InitialContext">javax.naming.ldap.InitialLdapContext</attribute>
</mbean>
<!-- Bind the /Scott filesystem directory -->
<mbean code="org.jboss.naming.ExternalContext"
name="DefaultDomain:service=ExternalContext/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
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
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
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
"ldap://ldaphost.displayscape.com:389/o=displayscape.com"
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[
<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
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
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
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>
</section>
