Author: ochikvina
Date: 2010-01-20 09:51:57 -0500 (Wed, 20 Jan 2010)
New Revision: 19825
Added:
trunk/jmx/docs/reference/en/modules/references.xml
trunk/jmx/docs/reference/en/modules/summary.xml
trunk/jmx/docs/reference/en/modules/tasks.xml
Log:
<html><head><meta name="qrichtext" content="1"
/></head><body style="font-size:9pt;font-family:Sans Serif">
<
p>https://jira.jboss.org/jira/browse/JBDS-907 restructured JMX guide.</p>
</body></html>
Added: trunk/jmx/docs/reference/en/modules/references.xml
===================================================================
--- trunk/jmx/docs/reference/en/modules/references.xml (rev 0)
+++ trunk/jmx/docs/reference/en/modules/references.xml 2010-01-20 14:51:57 UTC (rev
19825)
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="references" xreflabel="references">
+ <?dbhtml filename="references.html"?>
+ <title>References</title>
+
+ <section id="mbean_explorer" xreflabel="mbean_explorer">
+ <?dbhtml filename="mbean_explorer.html"?>
+
+ <title>MBean Explorer</title>
+ <para>The <property>MBean Explorer</property> displays the
MBean features (both attributes and operations) in its
+ hierarchy. Double-clicking on a feature will open a <property>MBean
Editor</property>, display the page
+ corresponding to the feature type and select the feature.</para>
+
+ <figure>
+ <title>MBean Explorer Features</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/mbean-explorer-features.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Since it's possible to have many MBean Editors opened at the
same time, the <property>MBean Explorer</property>
+ has the Link With Editor button
+
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata
fileref="images/link-with-editor_0.2.0.png"/>
+ </imageobject>
+ </inlinemediaobject>
+
+ to synchronize selections between the active <property>MBean
Editor</property> and
+ the <property>MBean Explorer</property> (and vice
versa).</para>
+
+ <para>The <property>MBean Explorer</property> has also a filter
text that can be used to filter among all the MBeans
+ the few ones, which interest you.</para>
+
+ <para>For example, if you are only interested by MBeans related to memory,
typing memo will show
+ any node (domain, mbean, attribute, or operation) that matches that text, as
well as
+ that node's parents and children. So if an MBean matches, all
attributes and operations from
+ that bean will show. If, however, an attribute or operation name (a leaf
node) matches,
+ only that node and its parents in the tree will show.</para>
+
+ <figure>
+ <title>Query Filter</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/mbean-explorer-query.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+
+ <para>The <emphasis>
+ <property>Collapse All</property></emphasis> button
+
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/collaps_all.png"/>
+ </imageobject>
+ </inlinemediaobject>
+
+ on the <property>MBean Explorer</property> toolbar is used to
collapse all the MBeans and
+ display only the domains. It is also possible to double click on a node to
expand/collapse it. </para>
+
+ </section>
+ <section id="mbean_editor" xreflabel="mbean_editor">
+ <?dbhtml filename="mbean_editor.html"?>
+
+ <title>MBean Editor</title>
+
+ <figure>
+ <title>MBean Editor Pages</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/mbean-editor_0.2.0.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The <property>MBean Editor</property> is composed of
several pages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <emphasis>
+ <property>Attributes</property></emphasis>
page</para>
+ </listitem>
+ <listitem>
+ <para>the <emphasis>
+ <property>Operations</property></emphasis>
page</para>
+ </listitem>
+ <listitem>
+ <para>the <emphasis>
+ <property>Notifications</property></emphasis> page
</para>
+ </listitem>
+ <listitem>
+ <para>the <emphasis>
+ <property>Info</property></emphasis> page
</para>
+ </listitem>
+ </itemizedlist>
+
+ <para> The <emphasis>
+ <property>Attributes</property>
+ </emphasis> and <emphasis>
+ <property>Operations</property>
+ </emphasis> pages display a list for either the MBean attributes or
operations as well as
+ details for the selection.</para>
+
+ <para> It is possible to toggle the layout between the list and the details
either vertically
+ (by default) or horizontally with the help of the special icons
+
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata
fileref="images/mbean-editor-layout-buttons_0.2.0.png"/>
+ </imageobject>
+ </inlinemediaobject>
+
+ in the right top corner of the editor.</para>
+
+ <figure>
+ <title>MBean Editor Horizontal Layout</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
fileref="images/mbean-editor-horizontal-layout_0.2.0.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section>
+ <title>Notifications Page</title>
+ <para>One more page in the <property>MBean
Editor</property> is the <emphasis>
+ <property>Notifications</property></emphasis> page,
which gives the possibility to
+ subscribe (resp. unsubscribe) to a MBean to receive its notifications by
checking (resp.
+ unchecking) the <emphasis>
+ <property>Subscribe</property></emphasis> button in
the right top corner. </para>
+ <para>The list of notifications is refreshed every time a new
notification is
+ received:</para>
+
+ <figure>
+ <title>MBean Editor Notifications Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/notifications.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <note>
+ <title>Note</title>
+ <para>It is only possible to subscribe to MBean, which emits
notifications (they must be
+ NotificationBroadcaster).</para>
+ </note>
+
+ </section>
+
+ </section>
+
+ </chapter>
Added: trunk/jmx/docs/reference/en/modules/summary.xml
===================================================================
--- trunk/jmx/docs/reference/en/modules/summary.xml (rev 0)
+++ trunk/jmx/docs/reference/en/modules/summary.xml 2010-01-20 14:51:57 UTC (rev 19825)
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter>
+ <?dbhtml filename="summary.html"?>
+ <title>Summary</title>
+ <para>In conclusion, with this document you could easily start with JXM Tools.
+ The chapters above walked you through the steps on how to do Tomcat,Eclipse
Equinox or JBoss Instances managing and how to create new JMX connections.
+ The document also includes the reference of JMX Tools features.
+
+ If you have questions or suggestions concerned both the documentation and tools
behavior,
+ you are welcome to JBoss Tools Users forum.
+ Please, use Jira to report bugs and requests on documentation.</para>
+
+ <section>
+ <title>Other relevant resources on the topic</title>
+ <para>All JBoss Developer Studio/JBoss Tools release documentation you can
find at
+ <ulink
url="http://docs.jboss.org/tools">http://docs.jboss.org/tool...
in the corresponding release directory.
+ </para>
+ <para>The latest documentation builds are available at <ulink
url="http://download.jboss.org/jbosstools/nightly-docs">http...;.
</para>
+ <para>You can find a set of benefits and other extra information
on:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink
url="http://www.jboss.org/community/wiki/JBossMX">JBoss Wiki</ulink>
+ </para>
+ </listitem>
+ <listitem><para>For more information about JMX technology please
visit
+ <ulink
url="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamana...
+ JMX Technology Home Page</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
\ No newline at end of file
Added: trunk/jmx/docs/reference/en/modules/tasks.xml
===================================================================
--- trunk/jmx/docs/reference/en/modules/tasks.xml (rev 0)
+++ trunk/jmx/docs/reference/en/modules/tasks.xml 2010-01-20 14:51:57 UTC (rev 19825)
@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="tasks" xreflabel="tasks">
+ <?dbhtml filename="tasks.html"?>
+ <title>JMX Tools Tasks</title>
+ <para>This chapter will give you answers on most popular questions asked by
<property>JMX
+ plugin</property> users.</para>
+ <section>
+ <title>Quick Start</title>
+
+ <para>To start using the <property>JMX Tools</property>,
it's necessary to open
+ <property>MBean Explorer</property>. Go to
<emphasis><property>Window > Show View >
Other</property></emphasis> and then select
+ <property>MBean Explorer</property> and click
<emphasis><property>OK</property>.</emphasis></para>
+
+ <para>The <property>MBean Explorer</property> lists all of the
domains, mbeans, attributes, and operations inside a
+ connection. When you double-click on a MBean in the
<emphasis><property>MBean Explorer</property>,</emphasis> it opens
a multi-page
+ editor to manage the MBean. The <property>MBean Editor</property>
is composed of these pages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis><property>Attributes
page</property>,</emphasis> to get/set the attributes of the
MBean</para>
+ </listitem>
+ <listitem>
+ <para><emphasis><property>Operations
page</property>,</emphasis> to invoke operations on the MBean</para>
+ </listitem>
+ <listitem>
+ <para><emphasis><property>Notifications
page</property>,</emphasis> to receive notifications from the
MBean</para>
+ </listitem>
+ <listitem>
+ <para><emphasis><property>Info
page</property>,</emphasis> which displays general information about the MBean
</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ <section>
+ <title>Tomcat Managing</title>
+
+ <para>It's possible to manage Tomcat using <property>JMX
Tools</property>.</para>
+
+ <para>Currently, JMX Tooling is able to connect to Tomcat without
authentication or with
+ password-based authentication.</para>
+ <para>Using SSL for authentication is not supported: you need to make sure
that the System
+ property <emphasis>
+ <property>com.sun.management.jmxremote.ssl</property>
+ </emphasis> is set to false. </para>
+ <para>More information to manage Tomcat can be found in Tomcat management
+ documentation.</para>
+ <para>Instructions to manage remotely Tomcat are available in
Tomcat's monitoring
+ documentation.</para>
+
+ </section>
+
+ <section>
+ <title>Eclipse Equinox Managing</title>
+
+ <para>You can manage Equinox through the Equinox monitoring
framework.</para>
+ <para>Once you have installed the Equinox monitoring framework and
restarted Eclipse:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Go to <emphasis>
+ <property>Window > Open Perspective >
Other</property>
+ </emphasis> and select the <property>JMX
perspective</property></para>
+ </listitem>
+
+ <listitem>
+ <para>Select <emphasis>
+ <property>JMX Server > Open Connection</property>
+ </emphasis> and click on <emphasis>
+ <property>OK</property>
+ </emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>Switch to the <property>MBean Explorer</property>
by going to <emphasis>
+ <property>Window > Show View >
Other</property>
+ </emphasis> and selecting the MBean Explorer</para>
+ </listitem>
+
+ <listitem>
+ <para>Click on the <emphasis>
+ <property>New Connection</property></emphasis> icon
+
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata
fileref="images/new_connection_icon.png"/>
+ </imageobject>
+ </inlinemediaobject>
+
+ in the <property>MBean Explorer</property> menu
+ bar </para>
+ </listitem>
+
+ <listitem>
+ <para>Select the <emphasis>
+ <property>Advanced tab</property></emphasis> and
set the JMX URL to <emphasis>
+
<property>service:jmx:rmi:///jndi/rmi://:8118/jmxserver</property>
+ </emphasis></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You now have access to the MBeans exposed by Equinox.</para>
+ </section>
+
+
+ <section>
+ <title>Managing JBoss Instances</title>
+
+ <para>Managing JBoss instances is not supported with the
<property>JMX Tools</property>
+ alone. You must also download and install the <property>AS
Tools</property> portion of
+ the <property>JBoss Tools</property> distribution. Even after
installing the proper
+ tooling, you cannot create a JBoss JMX connection yourself or through the
Connection
+ Wizard. The first step is to create a JBoss Server. The full instructions for
this can
+ be found in the AS Tools section, however, the short summary is:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>Open the <property>JBoss Servers View</property>
or the <property>Servers
+ View</property></para>
+ </listitem>
+
+ <listitem>
+ <para>Right-click in the view and select <emphasis>
+ <property>New > Server</property>
+ </emphasis></para>
+ </listitem>
+
+ <listitem>
+ <para>In the <emphasis>
+ <property>JBoss Community</property>
+ </emphasis> section, select a server version</para>
+ </listitem>
+
+ <listitem>
+ <para>If a runtime has not yet been created, you'll be
prompted for the
+ server's home directory, JDK, and configuration</para>
+ </listitem>
+
+ <listitem>
+ <para>Finish the wizard and note that you have a new entry in both
the
+ <property>JBoss Server View</property> and the
<property>MBean
+ Explorer</property></para>
+ </listitem>
+
+ <listitem>
+ <para>Start the server by right-clicking it and selecting
<emphasis>
+ <property>Start</property></emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Note that once the server is started, the JMX connection can
be
+ expanded</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Now you can explore MBeans exposed by a JBoss instance.</para>
+ </section>
+ <section id="extensions" xreflabel="extensions">
+ <title>Extension Task</title>
+ <para>This section will outline how to contribute your own Server type with
some default
+ behavior.</para>
+
+ <section>
+ <title>Why we should do that?</title>
+
+ <para>You might be asking yourself why you'd need to extend
this framework if JMX is
+ a standard. Perhaps you want a connection to be automatically created
after some specific
+ action, or perhaps you want your connection wizard to do more than simply
set a host and
+ port. JBoss, for example, requires setting some credentials on the client
machine, but
+ using JBoss classes to do it. This requires that the connection have
access to JBoss
+ jars.</para>
+ </section>
+
+ <section>
+ <title>Core Extensions</title>
+
+ <para>To create your own JMX Connection type, you must use the
+ org.jboss.tools.jmx.core.MBeanServerConnectionProvider extension point.
This point takes
+ one child, a connectionProvider with a class that implements
+ org.jboss.tools.jmx.core.IConnectionProvider.</para>
+
+ <para>An IConnectionProvider is responsible for creation and deletion
of IConnectionWrapper
+ objects. It must also keep a list of listeners that it is expected to
inform when a
+ connection is added or removed from its list. </para>
+
+ <para>Each IConnectionWrapper is expected to handle running arbitrary
JMX runnables or getting
+ a "Root" object representing all JMX nodes. There are some
utility methods the
+ IConnectionWrapper can make use of.</para>
+ </section>
+
+ <section>
+ <title>UI Extensions</title>
+ <para>There are two extension points currently approved for use in the
UI</para>
+ <itemizedlist>
+ <listitem>
+ <para>org.jboss.tools.jmx.ui.providerUI - provide an icon, id,
displayable name, and
+ wizardPage class for creation of new connections</para>
+ </listitem>
+ <listitem>
+ <para>org.jboss.tools.jmx.ui.attribute.controls - allows you to
map class types to some
+ Control to present them in the MBean Editor</para>
+ <para>We hope, this guide helped you to get started with the
JBoss JMX Tools. Besides, for additional information you are welcome on <ulink
+
url="http://www.jboss.com/index.html?module=bb&op=viewforum&...
forum</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ </section>
+ <section id="connection" xreflabel="connection">
+
+ <title>Connections Creation Task</title>
+
+ <para>The <property>MBean Explorer</property> supports several
different types of connections.
+ The tooling itself comes only with a default connection type, however other
+ adopters can provide additional connection types that may require additional
+ or non-spec behavior. Connections can be in either the connected state or
+ the disconnected state. Some connection types (such as the default connection
type)
+ allow you to control the current state. Other connection types may not.
</para>
+
+ <para>Similarly, some connection types may be able to be created, and
others may not.
+ The default connection type, for example, can be created and deleted by you
+ at will. The AS Tools connection type, which represents a JBoss server, does
not
+ allow you this level of control. A JBoss JMX connection is created when a
JBoss server is created
+ in the server's view, and deleted when said server is deleted. The JMX
connection for
+ this server is in the connected state only when the server is started.
</para>
+
+
+ <section><title>The Default Connection</title>
+
+ <para> There are two ways to connect to an application with remote
management enabled:</para>
+
+ <para> The first step is the same for both - to connect to a MBean
Server, click on the
+ <emphasis>
+ <property>New Connection</property></emphasis> icon
+
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata
fileref="images/new_connection_icon.png"/>
+ </imageobject>
+ </inlinemediaobject>
+
+ in the <property>MBean Explorer</property> menu
bar.</para>
+
+ <para>Then to follow the simple one you just need to specify host, port
(and optionally user
+ name and password) and click <emphasis>
+ <property>OK</property>.</emphasis></para>
+
+ <para>The default JMX URL is <emphasis>
+
<property>service:jmx:rmi:///jndi/rmi://localhost:3000/jmxrmi</property>.</emphasis></para>
+
+ <para>In case you need to connect to an application which has not used
the "standard" JMX URL
+ (e.g. Eclipse Equinox), you need chose more advance way, where
it's necessary to specify
+ explicitly a JMX URL in the Advanced tab of the JMX Connection
window.</para>
+
+ <note>
+ <title>Note</title>
+ <para>Only JMX URL based on RMI are supported.</para>
+ </note>
+ </section>
+ </section>
+</chapter>
+