User: stark
Date: 01/01/13 17:43:55
Added: documentation JMX.ExternalContext.HowTo.html
Log:
A HowTo document on the ExternalContext and JNDIView mbeans.
Revision Changes Path
1.1 newsite/documentation/JMX.ExternalContext.HowTo.html
Index: JMX.ExternalContext.HowTo.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>How To use the External JNDI Context and JNDIView MBeans</title>
<link rel="stylesheet" type="text/css" href="HowTo.css" >
</head>
<body>
<div class="page">
<h1>How To use the External JNDI Context and JNDIView MBeans</h1>
<h2>Introduction</h2>
<div class="para" align="left">
The External JNDI Context 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.
</div>
<div class="para" align="left">
The JNDIView MBean allows one to view the JNDI namespace tree as it exists
in the JBoss server using the JMX agent view interface.
</div>
<h2>Preparation of the ExternalContext MBean</h2>
<div class="para" align="left">
First you have to add the ExternalContext service to the jboss.jcml
in order to load the service. In the jboss.jcml the mbean tag looks
like this:
<pre class="code" align="left">
<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>
</MLET>
</pre>
where:
<ul>
<li>code="org.jboss.naming.ExternalContext" specifies the class that
impliments the
external context mbean.
</li>
<li>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.
</li>
<li>JndiName is the name with which the external context is bound into
the JBoss JNDI namespace</li>
<li>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.
</li>
</ul>
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:
<pre class="code" align="left">
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
</pre>
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:
<pre class="code" align="left">
InitialContext iniCtx = new InitialContext();
Context ldapCtx = iniCtx.lookup("external/ldap/dscape");
...
</pre>
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.
<h2>Preparation of the JNDIView MBean</h2>
<div class="para" align="left">
All that is required to use the JNDIView service is to add it to jboss.jcml
The mbean tag looks like this:
<pre class="code" align="left">
<mbean code="org.jboss.naming.JNDIView" name="DefaultDomain:service=JNDIView" >
</MLET>
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.
</div>
<h2>Using the JNDIView MBean</h2>
<div class="para" align="left">
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
<a href="http://localhost:8082/">http://localhost:8082/</a>. On this page you will
see a section that lists the registered MBeans by domain. It should look something
like this:
<div class="page">
<HR>
<H4>List of registered MBeans by domain:</H4>
<UL class="none" type=circle style="background-color: white">
<LI><STRONG>Adaptor</STRONG>
<UL type=disc style="background-color: white">
<LI><em>name=RMI</em>
<LI><em>name=html</em>
</UL><P>
<LI><STRONG>DefaultDomain</STRONG>
<UL type=disc style="background-color: white">
<LI><em>service=ClassPathExtension,name=../../db/</em>
<LI><em>service=ClassPathExtension,name=./</em>
<LI><em>...</em>
<LI><em>service=ExternalContext/FS</em>
<LI><em>service=ExternalContext/LDAP</em>
<LI><em>service=JNDIView</em>
<LI><em>...</em>
</ul>
</UL>
</div>
This is showing two registered ExternalContext mbeans(ExternalContext/FS[a
filesystem] and
ExternalContext/LDAP[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:
<div class="page">
<HR>
<P><H3> List of MBean operations:</H3>
<HR><B style="background-color:white">Description of list</B></A>
<FORM METHOD=GET>
<TABLE>
<TR><TD>java.lang.String</TD>
<TD><INPUT TYPE=SUBMIT NAME="action" VALUE="list"></TD>
<TD>(boolean)param0</TD>
<TD><INPUT TYPE=RADIO NAME="param0+boolean" CHECKED VALUE="true">True <INPUT
TYPE=RADIO NAME="param0+boolean" VALUE="false">False </TD>
</TR><TR><TD></TD>
</TR></TABLE>
</FORM>
<HR><B style="background-color:white">Description of destroy</B></A>
<p>...
</div>
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:
<div class="page">
<HR><P>
<FONT SIZE=+3 COLOR=green><B style="background-color:white">list
Successful</B></FONT><P><HR><P>The operation [list] was successfully invoked for the
MBean [DefaultDomain:service=JNDIView].<BR>The operation returned with the value:<P>
<pre> +- RMITopicConnectionFactory (class: org.spydermq.SpyTopicConnectionFactory)
+- TopicConnectionFactory (class: org.spydermq.SpyTopicConnectionFactory)
+- UILTopicConnectionFactory (class: org.spydermq.SpyTopicConnectionFactory)
+- RMIXATopicConnectionFactory (class: org.spydermq.SpyXATopicConnectionFactory)
+- XATopicConnectionFactory (class: org.spydermq.SpyXATopicConnectionFactory)
+- external: (class: org.jnp.interfaces.NamingContext)
| +- fs (class: org.jnp.interfaces.NamingContext)
| | +- temp (class: javax.naming.Context)
| | | +- APCcalc (class: javax.naming.Context)
| | | | +- APCalc-BW.prc (class: java.io.File)
| | | | +- APCalc-C.prc (class: java.io.File)
| | | | +- APCalcDoc.pdf (class: java.io.File)
| | | | +- APCalDB.PDB (class: java.io.File)
| | | | +- install.txt (class: java.io.File)
| | | | +- LICENSE.TXT (class: java.io.File)
| | | | +- MathLib.prc (class: java.io.File)
| | | +- control.xml (class: java.io.File)
| | | +- cvs (class: javax.naming.Context)
| | | +- Displayabs1.01.doc (class: java.io.File)
| | | +- ecdc_v403up.exe (class: java.io.File)
| | | +- FrontPageTempDir (class: javax.naming.Context)
| | | +- g3.dat (class: java.io.File)
| | | +- GLF849.tmp (class: java.io.File)
| | | +- h2r5C8.tmp (class: java.io.File)
| | | +- h2r697.tmp (class: java.io.File)
| | | +- h2rE69.tmp (class: java.io.File)
| | | +- h2rE6C.tmp (class: java.io.File)
| | | +- hs~34.tmp (class: java.io.File)
| | | +- hs~clear.htm (class: java.io.File)
| | | +- HTTP.TestHarness47723.gzip (class: java.io.File)
| | | +- ICO27D.tmp (class: java.io.File)
| | | +- ICO27F.tmp (class: java.io.File)
| | | +- ICO356.tmp (class: java.io.File)
| | | +- images (class: javax.naming.Context)
| | | | +- Activity.gif (class: java.io.File)
| | | | +- activity1.gif (class: java.io.File)
| | | | +- Calend.gif (class: java.io.File)
| | | | +- calendar1.gif (class: java.io.File)
| +- ldap (class: org.jnp.interfaces.NamingContext)
| | +- dscape (class: javax.naming.Context)
| | | +- ou=Directory Administrators (class:
javax.naming.directory.DirContext)
| | | +- ou=Groups (class: javax.naming.directory.DirContext)
| | | | +- cn=Accounting Managers (class:
javax.naming.directory.DirContext)
| | | | +- cn=HR Managers (class: javax.naming.directory.DirContext)
| | | | +- cn=PD Managers (class: javax.naming.directory.DirContext)
| | | | +- cn=DisplayScape Users (class: javax.naming.directory.DirContext)
| | | | +- cn=Roles Repository (class: javax.naming.directory.DirContext)
| | | +- ou=People (class: javax.naming.directory.DirContext)
| | | | +- uid=starksm (class: javax.naming.directory.DirContext)
| | | | +- uid=glennt (class: javax.naming.directory.DirContext)
| | | +- ou=Special Users (class: javax.naming.directory.DirContext)
| | | +- ou=Projects (class: javax.naming.directory.DirContext)
| | | | +- cn=NewProject1 (class: javax.naming.directory.DirContext)
| | | | | +- cn=Roles (class: javax.naming.directory.DirContext)
| | | | | | +- cn=ProjectOwner (class:
javax.naming.directory.DirContext)
| | | | | | +- cn=ProjectAdmin (class:
javax.naming.directory.DirContext)
| | | | | +- cn=Users (class: javax.naming.directory.DirContext)
| | | | | | +- userid=starksm (class:
javax.naming.directory.DirContext)
| | | | | | +- userid=glennt (class: javax.naming.directory.DirContext)
| | | | | +- cn=Documents (class: javax.naming.directory.DirContext)
| | | | | +- cn=Workflows (class: javax.naming.directory.DirContext)
| | | | +- cn=NewProject2 (class: javax.naming.directory.DirContext)
| | | | | +- cn=Roles (class: javax.naming.directory.DirContext)
| | | | | | +- cn=ProjectAdmin (class:
javax.naming.directory.DirContext)
| | | | | | +- cn=ProjectOwner (class:
javax.naming.directory.DirContext)
| | | | | +- cn=Users (class: javax.naming.directory.DirContext)
| | | | | | +- userid=starksm (class:
javax.naming.directory.DirContext)
| | | | | +- cn=Documents (class: javax.naming.directory.DirContext)
| | | | | +- cn=Workflows (class: javax.naming.directory.DirContext)
+- RMIQueueConnectionFactory (class: org.spydermq.SpyQueueConnectionFactory)
+- QueueConnectionFactory (class: org.spydermq.SpyQueueConnectionFactory)
+- UILQueueConnectionFactory (class: org.spydermq.SpyQueueConnectionFactory)
+- RMIXAQueueConnectionFactory (class: org.spydermq.SpyXAQueueConnectionFactory)
+- topic (class: org.jnp.interfaces.NamingContext)
| +- testDurableTopic (class: org.spydermq.SpyTopic)
| +- example (class: org.spydermq.SpyTopic)
| +- testTopic (class: org.spydermq.SpyTopic)
| +- metrics (class: org.spydermq.SpyTopic)
| +- bob (class: org.spydermq.SpyTopic)
| +- beancache (class: org.spydermq.SpyTopic)
+- XAQueueConnectionFactory (class: org.spydermq.SpyXAQueueConnectionFactory)
+- queue (class: org.jnp.interfaces.NamingContext)
| +- A (class: org.spydermq.SpyQueue)
| +- testQueue (class: org.spydermq.SpyQueue)
| +- controlQueue (class: org.spydermq.SpyQueue)
| +- ex (class: org.spydermq.SpyQueue)
| +- E (class: org.spydermq.SpyQueue)
| +- D (class: org.spydermq.SpyQueue)
| +- C (class: org.spydermq.SpyQueue)
| +- B (class: org.spydermq.SpyQueue)
+- UILXATopicConnectionFactory (class: org.spydermq.SpyXATopicConnectionFactory)
+- jmx:succubus-si:rmi (class: org.jboss.jmx.server.RMIConnectorImpl)
+- UILXAQueueConnectionFactory (class: org.spydermq.SpyXAQueueConnectionFactory)
+- jmx (class: org.jboss.jmx.server.JMXAdaptorImpl)
</pre>
</div>
</div>
<div class="footer" align="left">
If you comments/questions/problems, you can ask them on the jboss-user mail
list or contact myself at:
<a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a>.
</div>
</body>
</html>
