From jbosstools-commits at lists.jboss.org Wed Mar 11 09:27:33 2009 Content-Type: multipart/mixed; boundary="===============6762828807403836506==" MIME-Version: 1.0 From: jbosstools-commits at lists.jboss.org To: jbosstools-commits at lists.jboss.org Subject: [jbosstools-commits] JBoss Tools SVN: r14169 - trunk/jmx/docs/reference/en. Date: Wed, 11 Mar 2009 09:27:33 -0400 Message-ID: --===============6762828807403836506== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: smukhina Date: 2009-03-11 09:27:33 -0400 (Wed, 11 Mar 2009) New Revision: 14169 Added: trunk/jmx/docs/reference/en/master_output.xml Log: https://jira.jboss.org/jira/browse/JBDS-655 jmx guide file for release doc= s build added (done by smukhina) Added: trunk/jmx/docs/reference/en/master_output.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/jmx/docs/reference/en/master_output.xml (= rev 0) +++ trunk/jmx/docs/reference/en/master_output.xml 2009-03-11 13:27:33 UTC (= rev 14169) @@ -0,0 +1,523 @@ + + + + + + + + + = + + + + + + + + + + + = + + +]> + = + + JMX Tools Reference Guide + = + = + = + December 2008 + + 2007 + 2009 + JBoss, a division of Red Hat + + + Version: 1.0.0.GA = + + + + + PDF version + + + + + = + = + = + = + + + + Introduction + + JMX Tools allows to setup m= ultiple JMX connections and provides view + for exploring the JMX tree and execute operations directly from Eclips= e. + + This chapter covers the basics of working with JMX plugin, which is + used to manage Java applications through JMX and its RMI Connector. + +
+ JMX Tools + + + + + +
+ +
+ Requirements + Requirements to use JMX Tools are the following: + + + + JMX Tools is develope= d on Eclipse 3.4.x milestones + + + JMX Tools requires th= at Eclipse is run on a JDK 1.5.0 or above + (due to dependencies on JMX packages which were introduced in Ja= va 1.5.0) + + +
+ +
+ History + JBoss Tools' JMX project = is a fork of eclipse-j= mx, a project by Jeff Mesnil. + It was forked with permission. +
+ +
+ Installation + Here, we are going to explain how to install the JMX plugin into + Eclipse. + + JMX Tools is one module o= f the JBoss Tools + project. JMX Tools has no dep= endency on any other part of JBoss + Tools, and can be downloaded standalone. Even though th= e JMX + Tools have no dependencies, other plugins, such as AS Tools, + do depend on the JMX Tooling and even extend it. + + You can find the JBoss Tools plugins over at the download pages. The only + package you'll need to get is the JMX Tooling, however the AS + Tools would give you a more full experience when using = JMX with JBoss Servers. + You can find further download and installation instructions on the J= Boss Wiki in the InstallingJBossTools + section. +
+ + +
+ Quick Start + + To start using the JMX Tools, it's necessary to open + MBean Explorer. Go to Window > Show View > Other<= /emphasis> and then select + MBean Explorer and click OK. + + The MBean Explorer lists = all of the domains, mbeans, attributes, and operations inside a + connection. When you double-click on a MBean in the MBean Explorer, it opens a mult= i-page + editor to manage the MBean. The MBean Ed= itor is composed of these pages: + + + + Attributes page, to get/set the attributes of the MBean + + + Operations page, to invoke operations on the MBean + + + Notifications page, to receive notifications from the MBean + + + Info page,<= /emphasis> which displays general information about the MBean + + + +
+ + + + = + + + = + MBean Explorer + The MBean Explorer displa= ys the MBean features (both attributes and operations) in its + hierarchy. Double-clicking on a feature will open a MBean Editor, display the page + corresponding to the feature type and select the feature. + = +
+ MBean Explorer Features + + + = + + +
+ = + Since it's possible to have many MBean Editors opened at the sam= e time, the MBean Explorer + has the Link With Editor button = + = + = + + <= /imagedata> + + + = + to synchronize selections between the active MBean Editor and + the MBean Explorer (and vic= e versa). + = + The MBean Explorer has al= so a filter text that can be used to filter among all the MBeans + the few ones, which interest you. + = + For example, if you are only interested by MBeans related to mem= ory, typing memo will show + any node (domain, mbean, attribute, or operation) that matches tha= t text, as well as = + that node's parents and children. So if an MBean matches, all attr= ibutes 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. + +
+ Query Filter + + + + + +
+ + = + The + Collapse All but= ton = + = + = + + + + + = + on the MBean Explorer toolb= ar 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. + = + + + = + + + + MBean Editor + +
+ MBean Editor Pages + + + + + +
+ + The MBean Editor is compo= sed of several pages: + + + + the Attributes page + + + the Operations page + + + the Info page + + + + The + Attributes + and + Operations + pages display a list for either the MBean attributes o= r operations as well as + details for the selection. + + It is possible to toggle the layout between the list and the de= tails either vertically + (by default) or horizontally with the help of the special icons = + = + = + + + + + = + in the right top corner of the editor. + +
+ MBean Editor Horizontal Layout + + + + + +
+ +
+ Notifications Page + One more page in the MBean Edito= r is a Notifications Page, which gives the possibility to + subscribe (resp. unsubscribe) to a MBean to receive its notifi= cations by checking (resp. + unchecking) the Subscribe checkbox. + The list of notifications is refreshed every time a new noti= fication is + received: + + + Note + It is only possible to subscribe to MBean, which emits n= otifications (they must be + NotificationBroadcaster). + + +
+ + + + = + + + = + Connections + + The MBean Explorer suppor= ts several different types of connections. = + The tooling itself comes only with a default connection type, ho= wever other + adopters can provide additional connection types that may requir= e additional + or non-spec behavior. Connections can be in either the connected= state or + the disconnected state. Some connection types (such as the defau= lt connection type) + allow you to control the current state. Other connection types m= ay not. + = + Similarly, some connection types may be able to be created, and = others may not. = + The default connection type, for example, can be created and del= eted 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 creat= ed when a JBoss server is created + in the server's view, and deleted when said server is deleted. T= he JMX connection for = + this server is in the connected state only when the server is st= arted. + + +
The Default Connection + = + There are two ways to connect to an application with remote = management enabled: + = + The first step is the same for both - to connect to a MBean = Server, click on the + + New Connection icon = + = + = + + <= /imagedata> + + + = + in the MBean Explorer me= nu bar. + = + Then to follow the simple one you just need to specify host, = port (and optionally user + name and password) and click + OK. + = + The default JMX URL is + service:jmx:rmi:///jndi/rmi://loca= lhost:3000/jmxrmi. + = + In case you need to connect to an application which has not u= sed 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. + = + + Note + Only JMX URL based on RMI are supported. + +
+ + + = + + + How to ... + This chapter will give you answers on most popular questions ask= ed by JMX + plugin users. + +
+ How to Manage Tomcat + + It's possible to manage Tomcat using JMX Tools. + + Currently, JMX Tooling is able to connect to Tomcat without = authentication or with + password-based authentication. + Using SSL for authentication is not supported: you need to m= ake sure that the System + property + com.sun.management.jmxremote.s= sl + is set to false. + More information to manage Tomcat can be found in Tomcat man= agement + documentation. + Instructions to manage remotely Tomcat are available in Tomc= at's monitoring + documentation. + +
+ +
+ How to manage Eclipse Equinox + + You can manage Equinox through the Equinox monitoring framew= ork. + Once you have installed the Equinox monitoring framework and= restarted Eclipse: + + + + Go to + Window > Open Persp= ective > Other + and select the JMX perspective + + + + Select + JMX Server > Open C= onnection + and click on + OK + + + + + Switch to the MBean Expl= orer by going to + Window > Show View = > Other + and selecting the MBean Explorer + + + + Click on the + New Connection<= /emphasis> icon = + = + = + + + + + = + in the MBean Explorer menu + bar + + + + Select the + Advanced tab and set the JMX URL to + service:jmx:rmi:///jnd= i/rmi://:8118/jmxserver + + + + + You now have access to the MBeans exposed by Equinox. +
+ + +
+ Managing JBoss Instances + + Managing JBoss instances is not supported with the JMX Tools + alone. You must also download and install the AS Tools portion of + the JBoss Tools distrib= ution. 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 i= nstructions for this can + be found in the AS Tools section, however, the short summary i= s: + + + Open the JBoss Servers V= iew or the Servers + View + + + + Right-click in the view and select + New > Server + + + + + In the + JBoss Community + section, select a server version + + + + If a runtime has not yet been created, you'll be pro= mpted for the + server's home directory, JDK, and configuration + + + + Finish the wizard and note that you have a new entry= in both the + JBoss Server View and the MBean + Explorer + + = + + Start the server by right-clicking it and selecting = + Start + + + Note that once the server is started, the JMX connec= tion can be + expanded + + + + Now you can explore MBeans exposed by a JBoss instance. +
+ + + + = + + + Extension API + This chapter will outline how to contribute your own Server type = with some default + behavior. + +
+ Why?? + + You might be asking yourself why you'd need to extend this fra= mework if JMX is + a standard. Perhaps you want a connection to be automatically cre= ated after some specific + action, or perhaps you want your connection wizard to do more tha= n simply set a host and + port. JBoss, for example, requires setting some credentials on th= e client machine, but + using JBoss classes to do it. This requires that the connection h= ave access to JBoss + jars. +
+ +
+ Core Extensions + + 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. + = + An IConnectionProvider is resposnbile for creation and deletio= n of IConnectionWrapper + objects. It must also keep a list of listeners that it is expecte= d to inform when a + connection is added or removed from its list. + = + Each IConnectionWrapper is expected to handle running arbitrar= y JMX runnables or getting + a "Root" object representing all JMX nodes. There are some utilit= y methods the + IConnectionWrapper can make use of. +
+ + +
+ UI Extensions + There are two extension points currently approved for use in t= he UI + + + org.jboss.tools.jmx.ui.providerUI - provide an icon, id,= displayable name, and + wizardPage class for creation of new connections + + + org.jboss.tools.jmx.ui.attribute.controls - allows you t= o map class types to some + Control to present them in the MBean Editor + + +
+ + + + --===============6762828807403836506==--