[jbosstools-commits] JBoss Tools SVN: r15194 - branches/jbosstools-3.0.x/jmx/docs/reference/en.

Author: smukhina Date: 2009-05-11 12:34:05 -0400 (Mon, 11 May 2009) New Revision: 15194 Added: branches/jbosstools-3.0.x/jmx/docs/reference/en/master_output.xml Log: https://jira.jboss.org/jira/browse/JBDS-717 merged changes from trunk are added to the corresponding branch Copied: branches/jbosstools-3.0.x/jmx/docs/reference/en/master_output.xml (from rev 15128, trunk/jmx/docs/reference/en/master_output.xml) =================================================================== --- branches/jbosstools-3.0.x/jmx/docs/reference/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.x/jmx/docs/reference/en/master_output.xml 2009-05-11 16:34:05 UTC (rev 15194) @@ -0,0 +1,542 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[<!ENTITY introduction SYSTEM "modules/introduction.xml"> +<!ENTITY mbean_explorer SYSTEM "modules/mbean_explorer.xml"> +<!ENTITY mbean_editor SYSTEM "modules/mbean_editor.xml"> +<!ENTITY connection SYSTEM "modules/connection.xml"> +<!ENTITY how_to SYSTEM "modules/how_to.xml"> +<!ENTITY extensions SYSTEM "modules/extensions.xml"> + + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + + <bookinfo> + <title>JMX Tools Reference Guide</title> + + <!--author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author&gt;&lt;firstname&gt;Rob&lt;/firstname&gt;&lt;surname&gt;Stryker&lt;/surname&gt;&lt;email&gt;rob.stryker(a)jboss.com&lt;/email&gt;&lt;/author&gt; + <author&gt;&lt;firstname&gt;Svetlana&lt;/firstname&gt;&lt;surname&gt;Mukhina&lt;/surname&gt;&lt;email&gt;smukhina(a)exadel.com&lt;/email&gt;&lt;/author--&gt; + + <pubdate>December 2008</pubdate> + <copyright> + <year>2007</year> + <year>2009</year> + <holder>JBoss, a division of Red Hat</holder> + </copyright> + <releaseinfo> + Version: 1.0.0.GA + </releaseinfo> +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/as/pdf/JMX... version</ulink> + </para> +</abstract> + + </bookinfo> + + + <toc></toc> + +<chapter id="intruduction" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/introduction.xml" xreflabel="introduction"> + <?dbhtml filename="introduction.html"?> + + <title>Introduction</title> + + <para><property moreinfo="none">JMX Tools</property> allows to setup multiple JMX connections and provides view + for exploring the JMX tree and execute operations directly from Eclipse.</para> + + <para>This chapter covers the basics of working with <property moreinfo="none">JMX plugin</property>, which is + used to manage Java applications through JMX and its RMI Connector.</para> + + <figure float="0"> + <title>JMX Tools</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/eclipse-jmx_0.2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section> + <title> Requirements </title> + <para>Requirements to use <property moreinfo="none">JMX Tools</property> are the following:</para> + + <itemizedlist> + <listitem> + <para><property moreinfo="none">JMX Tools</property> is developed on Eclipse 3.4.x milestones</para> + </listitem> + <listitem> + <para><property moreinfo="none">JMX Tools</property> requires that Eclipse is run on a JDK 1.5.0 or above + (due to dependencies on JMX packages which were introduced in Java 1.5.0)</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>History</title> + <para><property moreinfo="none">JBoss Tools</property>' JMX project is a fork of <ulink url="http://code.google.com/p/eclipse-jmx/">eclipse-jmx</...;, a project by Jeff Mesnil. + It was forked with permission. </para> + </section> + + <section> + <title>Installation</title> + <para>Here, we are going to explain how to install the <property moreinfo="none">JMX plugin</property> into + Eclipse.</para> + + <para><property moreinfo="none">JMX Tools</property> is one module of the <property moreinfo="none">JBoss Tools</property> + project. <property moreinfo="none">JMX Tools</property> has no dependency on any other part of <property moreinfo="none">JBoss + Tools</property>, and can be downloaded standalone. Even though the <property moreinfo="none">JMX + Tools</property> have no dependencies, other plugins, such as <property moreinfo="none">AS Tools</property>, + do depend on the JMX Tooling and even extend it. </para> + + <para>You can find the <property moreinfo="none">JBoss Tools</property> plugins over at the <ulink url="http://labs.jboss.com/tools/download/index.html">download pages</ulink>. The only + package you'll need to get is the JMX Tooling, however the <property moreinfo="none">AS + Tools</property> would give you a more full experience when using JMX with JBoss Servers. + You can find further download and installation instructions on the JBoss Wiki in the <ulink url="http://labs.jboss.com/wiki/InstallingJBossTools">Instal... + section.</para> + </section> + + + <section> + <title>Quick Start</title> + + <para>To start using the <property moreinfo="none">JMX Tools</property>, it's necessary to open + <property moreinfo="none">MBean Explorer</property>. Go to <emphasis><property moreinfo="none">Window &gt; Show View &gt; Other</property></emphasis> and then select + <property moreinfo="none">MBean Explorer</property> and click <emphasis><property moreinfo="none">OK</property>.</emphasis></para> + + <para>The <property moreinfo="none">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 moreinfo="none">MBean Explorer</property>,</emphasis> it opens a multi-page + editor to manage the MBean. The <property moreinfo="none">MBean Editor</property> is composed of these pages:</para> + + <itemizedlist> + <listitem> + <para><emphasis><property moreinfo="none">Attributes page</property>,</emphasis> to get/set the attributes of the MBean</para> + </listitem> + <listitem> + <para><emphasis><property moreinfo="none">Operations page</property>,</emphasis> to invoke operations on the MBean</para> + </listitem> + <listitem> + <para><emphasis><property moreinfo="none">Notifications page</property>,</emphasis> to receive notifications from the MBean</para> + </listitem> + <listitem> + <para><emphasis><property moreinfo="none">Info page</property>,</emphasis> which displays general information about the MBean </para> + </listitem> + </itemizedlist> + + </section> + +</chapter> + + +<chapter id="mbean_explorer" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/mbean_explorer.xml" xreflabel="mbean_explorer"> + <?dbhtml filename="mbean_explorer.html"?> + + <title>MBean Explorer</title> + <para>The <property moreinfo="none">MBean Explorer</property> displays the MBean features (both attributes and operations) in its + hierarchy. Double-clicking on a feature will open a <property moreinfo="none">MBean Editor</property>, display the page + corresponding to the feature type and select the feature.</para> + + <figure float="0"> + <title>MBean Explorer Features</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/mbean-explorer-features.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Since it's possible to have many MBean Editors opened at the same time, the <property moreinfo="none">MBean Explorer</property> + has the Link With Editor button + + <inlinemediaobject> + <imageobject> + <imagedata fileref="images/link-with-editor_0.2.0.png"></imagedata> + </imageobject> + </inlinemediaobject> + + to synchronize selections between the active <property moreinfo="none">MBean Editor</property> and + the <property moreinfo="none">MBean Explorer</property> (and vice versa).</para> + + <para>The <property moreinfo="none">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 float="0"> + <title>Query Filter</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/mbean-explorer-query.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + + <para>The <emphasis> + <property moreinfo="none">Collapse All</property></emphasis> button + + <inlinemediaobject> + <imageobject> + <imagedata fileref="images/collaps_all.png"></imagedata> + </imageobject> + </inlinemediaobject> + + on the <property moreinfo="none">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> + +</chapter> + + +<chapter id="mbean_editor" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/mbean_editor.xml" xreflabel="mbean_editor"> + <?dbhtml filename="mbean_editor.html"?> + + <title>MBean Editor</title> + + <figure float="0"> + <title>MBean Editor Pages</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/mbean-editor_0.2.0.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <property moreinfo="none">MBean Editor</property> is composed of several pages:</para> + + <itemizedlist> + <listitem> + <para><diffmk:wrapper diffmk:change="added">the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Attributes</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> page</diffmk:wrapper></para> + </listitem> + <listitem diffmk:change="added"> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Operations</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> page</diffmk:wrapper></para> + </listitem> + <listitem> + <para><diffmk:wrapper diffmk:change="added">the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Notifications</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> page </diffmk:wrapper></para> + </listitem> + <listitem> + <para><diffmk:wrapper diffmk:change="added">the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Info</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> page </diffmk:wrapper></para> + </listitem> + </itemizedlist> + + <para> The <emphasis> + <property moreinfo="none">Attributes</property> + </emphasis> and <emphasis> + <property moreinfo="none">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"></imagedata> + </imageobject> + </inlinemediaobject> + + in the right top corner of the editor.</para> + + <figure float="0"> + <title>MBean Editor Horizontal Layout</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/mbean-editor-horizontal-layout_0.2.0.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section> + <title>Notifications Page</title> + <para>One more page in the <property moreinfo="none">MBean Editor</property><diffmk:wrapper diffmk:change="added"> is the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Notifications</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> page, which gives the possibility to + subscribe (resp. unsubscribe) to a MBean to receive its notifications by checking (resp. + unchecking) the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Subscribe</diffmk:wrapper></property></emphasis><diffmk:wrapper diffmk:change="added"> button in the right top corner. </diffmk:wrapper></para> + <para><diffmk:wrapper diffmk:change="changed">The list of notifications is refreshed every time a new notification is + received:</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">MBean Editor Notifications Page</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/notifications.png"></imagedata> + </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> + +</chapter> + + +<chapter id="connection" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/connection.xml" xreflabel="connection"> + <?dbhtml filename="connection.html"?> + + <title>Connections</title> + + <para>The <property moreinfo="none">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 moreinfo="none">New Connection</property></emphasis> icon + + <inlinemediaobject> + <imageobject> + <imagedata fileref="images/new_connection_icon.png"></imagedata> + </imageobject> + </inlinemediaobject> + + in the <property moreinfo="none">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 moreinfo="none">OK</property>.</emphasis></para> + + <para>The default JMX URL is <emphasis> + <property moreinfo="none">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> +</chapter> + + +<chapter id="how_to" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/how_to.xml" xreflabel="how_to"> + <?dbhtml filename="how_to.html"?> + <title>How to ...</title> + <para>This chapter will give you answers on most popular questions asked by <property moreinfo="none">JMX + plugin</property> users.</para> + + <section> + <title>How to Manage Tomcat</title> + + <para>It's possible to manage Tomcat using <property moreinfo="none">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 moreinfo="none">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>How to manage Eclipse Equinox</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 moreinfo="none">Window &gt; Open Perspective &gt; Other</property> + </emphasis> and select the <property moreinfo="none">JMX perspective</property></para> + </listitem> + + <listitem> + <para>Select <emphasis> + <property moreinfo="none">JMX Server &gt; Open Connection</property> + </emphasis> and click on <emphasis> + <property moreinfo="none">OK</property> + </emphasis></para> + </listitem> + + <listitem> + <para>Switch to the <property moreinfo="none">MBean Explorer</property> by going to <emphasis> + <property moreinfo="none">Window &gt; Show View &gt; Other</property> + </emphasis> and selecting the MBean Explorer</para> + </listitem> + + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">New Connection</property></emphasis> icon + + <inlinemediaobject> + <imageobject> + <imagedata fileref="images/new_connection_icon.png"></imagedata> + </imageobject> + </inlinemediaobject> + + in the <property moreinfo="none">MBean Explorer</property> menu + bar </para> + </listitem> + + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Advanced tab</property></emphasis> and set the JMX URL to <emphasis> + <property moreinfo="none">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 moreinfo="none">JMX Tools</property> + alone. You must also download and install the <property moreinfo="none">AS Tools</property> portion of + the <property moreinfo="none">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 moreinfo="none">JBoss Servers View</property> or the <property moreinfo="none">Servers + View</property></para> + </listitem> + + <listitem> + <para>Right-click in the view and select <emphasis> + <property moreinfo="none">New &gt; Server</property> + </emphasis></para> + </listitem> + + <listitem> + <para>In the <emphasis> + <property moreinfo="none">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 moreinfo="none">JBoss Server View</property> and the <property moreinfo="none">MBean + Explorer</property></para> + </listitem> + + <listitem> + <para>Start the server by right-clicking it and selecting <emphasis> + <property moreinfo="none">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> + +</chapter> + + +<chapter id="extensions" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jmx/docs/reference/en/modules/extensions.xml" xreflabel="extensions"> + <?dbhtml filename="extensions"?> + <title>Extension API</title> + <para>This chapter will outline how to contribute your own Server type with some default + behavior.</para> + + <section> + <title>Why??</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><diffmk:wrapper diffmk:change="changed">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. </diffmk:wrapper></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><diffmk:wrapper diffmk:change="added">org.jboss.tools.jmx.ui.attribute.controls - allows you to map class types to some + Control to present them in the MBean Editor</diffmk:wrapper></para> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">We hope, this guide helped you to get started with the JBoss JMX Tools. Besides, for additional information you are welcome on </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... diffmk:change="added">JBoss forum</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + </listitem> + </itemizedlist> + </section> + +</chapter> + +</book>