[jboss-svn-commits] JBL Code SVN: r32129 - in labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US: images and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Mar 17 22:00:00 EDT 2010
Author: misty at redhat.com
Date: 2010-03-17 21:59:59 -0400 (Wed, 17 Mar 2010)
New Revision: 32129
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Tools.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-object_store_browser_window.png
Modified:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
Log:
Added Tools chapter
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-18 01:03:40 UTC (rev 32128)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-18 01:59:59 UTC (rev 32129)
@@ -12,6 +12,7 @@
<xi:include href="JBossTS-Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Failure_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JTA_and_JTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<index />
</book>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Tools.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Tools.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Tools.xml 2010-03-18 01:59:59 UTC (rev 32129)
@@ -0,0 +1,390 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>Tools</title>
+ <para>
+ This chapter explains how to start and use the tools framework the available tools.
+ </para>
+ <section>
+ <title>Starting the Transaction Service Tools</title>
+ <para>
+ Instructions for starting the Transaction Service Tools are listed below, and differ based on the operating system being used.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Windows</term>
+ <listitem><para>Double-click on the <guilabel>Start Tools</guilabel> link in the JBoss Transaction Service program group in the start menu.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UNIX</term>
+
+ <listitem>
+
+ <procedure>
+ <step><para>Start a terminal instance and type:</para>
+ <screen>cd <replaceable>JBossTS INSTALL DIRECTORY</replaceable></screen><screen>./run-tools.sh</screen></step>
+ <step><para>The Tools window appears. This is the launch area for all of the tools shipped with the JBoss Transaction Service. A menu bar is at the top of the screen.</para></step>
+ </procedure>
+
+ <itemizedlist>
+
+ <listitem>
+ <para><guilabel>File</guilabel> Menu options:</para>
+ <itemizedlist>
+ <listitem><para><guilabel>Open JMX Browser</guilabel> displays the JMX Browser window.</para></listitem>
+ <listitem><para><guilabel>Object Store Browser</guilabel> displays the <application>JBoss Transaction Service</application> Object Store browser window.</para></listitem>
+ <listitem><para><guilabel>Settings</guilabel> contains items for viewing and editing settings.</para></listitem>
+ <listitem><para><guilabel>Exit</guilabel> exits the program.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem><para><guilabel>Performance</guilabel> contains items relating to system performance. <menuchoice><guilabel>Performace</guilabel><guilabel>Close All</guilabel></menuchoice> closes all performance windows.</para></listitem>
+
+ <listitem><para><guilabel>Window</guilabel> contains items for manipulating, viewing, and selecting open windows.</para></listitem>
+
+ <listitem><para><guilabel>Help</guilabel> contains items pertaining to the Help system.</para></listitem>
+
+ <listitem><para><guilabel>About</guilabel> contains version and licensing information, and credits.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+
+ <section>
+ <title>Using the Performance Tool</title>
+ <para>
+ The performance tool displays performance information about the transaction service. This information is gathered using the Performance JMX bean. The transaction service must be integrated into an Application Server to to function properly.
+ </para>
+ <para>
+ The performance information is displayed via a multi-series graph. View the graph by selecting <menuchoice><guilabel>Performance</guilabel><guilabel>Open</guilabel></menuchoice>.
+ </para>
+ <para>
+ The graph displays the following information:
+ </para>
+ <itemizedlist>
+ <listitem><para>Number of transactions.</para></listitem>
+ <listitem><para>Number of committed transactions.</para></listitem>
+ <listitem><para>Number of aborted transactions.</para></listitem>
+ <listitem><para>Number of nested transactions.</para></listitem>
+ <listitem><para>Number of heuristics raised.</para></listitem>
+ </itemizedlist>
+ <para>
+ To turn these series on and off, select <menuchoice><guilabel>Menu</guilabel><guilabel>Series</guilabel></menuchoice>.
+ </para>
+ <para>
+ Visible series appear in the legend at the bottom of the graph, along with the colours representing them on the graph.
+ </para>
+ <para>
+ The Y-axis represents the number of transactions and the X-axis represents time.
+ </para>
+ <para>
+ Data sampling can be stopped and restarted at any time using the <guilabel>Sampling</guilabel> menu.
+ </para>
+ <note>
+ <para>
+ The data currently visible in the graph can be saved to a CSV (comma separated value) file by means of the <menuchoice><guilabel>Data</guilabel><guilabel>Save to .csv</guilabel></menuchoice> menu option.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Using the JMX Browser</title>
+ <para>
+ To open the JMX browser window, click the <menuchoice><guilabel>File</guilabel><guilabel>Open JMX Browser Option</guilabel></menuchoice> menu item. The JMX browser window is displayed.
+ </para>
+ <para>
+ The window is divided into two main sections:
+ <itemizedlist>
+ <listitem><para>Details</para></listitem>
+ <listitem><para>MBean</para></listitem>
+ </itemizedlist>
+ The MBean panel displays the MBeans exposed by the MBean server. These are grouped by domain name. The details panel displays information about the currently selected MBean. To select an MBean just left-click it with the mouse and it will become highlighted. The information displayed in the details panel is as follows:
+ </para>
+ <itemizedlist>
+ <listitem><para>The total number of MBeans registered on this server,</para></listitem>
+ <listitem><para>The number of constructors exposed by this MBean,</para></listitem>
+ <listitem><para>The number of attributes exposed by this MBean,</para></listitem>
+ <listitem><para>The number of operations exposed by this MBean,</para></listitem>
+ <listitem><para>The number of notifications exposed by this MBean,</para></listitem>
+ <listitem><para>A brief description of the MBean.</para></listitem>
+ </itemizedlist>
+
+ <para>
+ The <guilabel>View</guilabel> link displays the attributes and operations exposed by an MBean. Use this link to view and interact with attributres and operations.
+ </para>
+ <section>
+ <title>Using Attributes and Operations</title>
+ <para>
+ When the <guilabel>View</guilabel> link is clicked the <guilabel>View JMX Attributes and Operations</guilabel> window appears. Use this to view all readable attributes exposed by the selected MBean. Only writeable attributes can be altered. To alter an attribute's value, double-click the current value and enter the new value. If the button is enabled, you can click this for additional editing options. If the attribute type is a JMX object name, clicking the button displays its JMX attributes and operations.
+ </para>
+ <para>
+ After making changes, click the <guilabel>Refresh</guilabel> button to verify that your changes have taken effect. If an exception occurs while retrieving the value of an attribute, the exception is displayed instead of the attribute's value.
+ </para>
+ <para>
+ You can also invoke operations upon an MBean. A list of operations exposed by an MBean is displayed below the Attributes list. To invoke an operation, select it from the list and click the <guilabel>Invoke</guilabel> button. If the operation requires parameters, you are prompted for them. Specify parameter values in the same way as you specify JMX attribute values. After filling in the appropriate values, click the <guilabel>Invoke</guilabel> button to perform the invocation. After the operation has completed, the return value is displayed.
+ </para>
+
+ </section>
+ </section>
+
+ <section>
+ <title>Using the Object Store Browser</title>
+ <para>
+ To open the Object Store browser window, click the <menuchoice><guilabel>File</guilabel><guilabel>Open Object Store Browser</guilabel></menuchoice> menu item. The Object Store browser window is displayed.
+ </para>
+ <para>
+ The object store browser window is split into four sections:
+ </para>
+
+ <figure>
+ <title>The Object Store Browser Window</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure-object_store_browser_window.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>The Object Store Browser Window is split into four sections.</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <variablelist>
+ <varlistentry>
+ <term>Objet Store Roots</term>
+ <listitem><para>A list of the currently available object store roots. Selecting an option from the list will repopulate the hierarchy view with the contents of the selected root.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Object Store Hierarchy</term>
+ <listitem><para>A tree view of the current object store hierarchy. Selecting a node from this tree will display the objects stored in that location.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Objects</term>
+ <listitem><para>A list of the objects stored in the selected location.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Object Details</term>
+ <listitem><para>Information about the currently selected object (only if the object’s type is known to the state viewer repository. <remark>Fix Me</remark>See Writing an OSV for information on how to write a object state viewers).</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <section>
+ <title>Object State Viewers (OSV)</title>
+ <para>
+ Selected an object in the objects pane of the main window to invoke its registered OSV. An OSV makes information about the selected object available via the user interface. An OSV for Atomic Actions is distributed with the standard tools. This OSV displays information on the Abstract Records in its various lists (e.g. heuristic, failed, read-only, etc). You can write your own OSVs to display information about object types you have defined.
+ </para>
+
+ <section>
+ <title>Writing an OSV</title>
+ <para>
+ Writing an OSV plugin allows you to extend the capabilities of the Object Store browser to show the state of user defined abstract records. An OSV plug-in is simply a class which implements the <classname>com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface</classname> interface. It must be packaged in a JAR within the plugins directory. The following example creates an OSV plugin for an abstract record subclass:
+ </para>
+
+ <programlisting role="JAVA" language="Java">
+ public class SimpleRecord extends AbstractRecord
+ {
+ private int _value = 0;
+
+ .....
+
+ public void increase()
+ {
+ _value++;
+ }
+
+ public int get()
+ {
+ return _value;
+ }
+
+ public String type()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+
+ public boolean restore_state(InputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ _value = os.unpackInt();
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+
+ public boolean save_state(OutputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ os.packInt(_value);
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+ }
+ </programlisting>
+
+ <para>
+ When this abstract record is viewed in the object store browser, the current value is useful. This can be done by reading the state into an instance of the abstract record and calling getValue(). The full source code is below:
+ </para>
+
+ <programlisting role="JAVA" language="Java">
+ public class SimpleRecordOSVPlugin implements StateViewerInterface
+ {
+ /**
+ * A uid node of the type this viewer is registered against has been expanded.
+ * @param os
+ * @param type
+ * @param manipulator
+ * @param node
+ * @throws ObjectStoreException
+ */
+ public void uidNodeExpanded(ObjectStore os,
+ String type,
+ ObjectStoreBrowserTreeManipulationInterface
+ manipulator,
+ UidNode node,
+ StatePanel infoPanel)
+ throws ObjectStoreException
+ {
+ // Do nothing
+ }
+
+ /**
+ * An entry has been selected of the type this viewer is registered against.
+ *
+ * @param os
+ * @param type
+ * @param uid
+ * @param entry
+ * @param statePanel
+ * @throws ObjectStoreException
+ */
+ public void entrySelected(ObjectStore os,
+ String type,
+ Uid uid,
+ ObjectStoreViewEntry entry,
+ StatePanel statePanel)
+ throws ObjectStoreException
+ {
+ SimpleRecord rec = new SimpleRecord();
+
+ if ( rec.restore_state( os.read_committed(uid, type), ObjectType.ANDPERSISTENT ) )
+ {
+ statePanel.setData( “Value”, rec.getValue() );
+ }
+ }
+
+ /**
+ * Get the type this state viewer is intended to be registered against.
+ * @return
+ */
+ public String getType()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+ }
+ </programlisting>
+
+ <para>
+ The method <methodname>uidNodeExpanded</methodname> is invoked when a UID (Unique Identification) representing the given type is expanded in the object store hierarchy tree. This is not a plugin requirement because this abstract record is not visible in the object store directly, but only via one of the lists in an atomic action. The method <methodname>entrySelected</methodname> is invoked when an object is selected which is of the given type. In both methods the StatePanel displays information regarding the state of the object. The state panel uses the following methods:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><methodname>setInfo(String info)</methodname></term>
+ <listitem><para>Shows general information abou the object.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>setData(String name, String value)</methodname></term>
+ <listitem><para>Populates the table which is displayed by the object store browser tool.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>enableDetailsButton(DetailsButtonListener listener)</methodname></term>
+ <listitem><para>Enables the <guilabel>Details</guilabel> button. The listener interface allows a plug-in to detect when the button is pressed. It is the plug-in developer's responsibility to decide how to display this information.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ This example reads the state from the object store and uses the value returned by <methodname>getValue()</methodname> to insert an entry into the state panel table. The <methodname>getType()</methodname> method returns this plugin's type.
+ </para>
+ <para>
+ To add this plug-in to the object store browser, package it into a JAR file with the prefix 'osbv-'. The JAR file must contain certain information in the manifest file to tell the objectct store browser which classes refer to plug-ins. An Apache ANT (http://ant.apache.org) script can automate this process, as follows:
+ </para>
+
+ <screen>
+ <jar jarfile="osbv-simplerecord.jar">
+ <fileset dir="build" includes="*.class”/>
+ <manifest>
+ <section name="arjuna-tools-objectstorebrowser">
+ <attribute name="plugin-classname-1" value=" SimpleRecordOSVPlugin "/>
+ </section>
+ </manifest>
+ </jar>
+ </screen>
+
+ <para>
+ After the JAR has been created, it must be placed in the <filename>bin/tools/plugins</filename> directory.
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>RMIC Extensions</title>
+ <para>
+ The RMIC (Remote Method Invocation Compiler) extensions generate stubs and tie classes for transactional RMI-IIOP (RMI Interface Over the Internet) objects. A transactional object is an object whichreceives transactional context when one of its methods is invoked. Without transactional object support, an RMI-IIOP object will not receive its transactional context when its methods are invoked.
+ </para>
+ <para>
+ The RMIC works in two ways:
+ <itemizedlist>
+ <listitem><para>via the command line</para></listitem>
+ <listitem><para>via ANTs RMIC compiler task</para></listitem>
+ </itemizedlist>
+ Examples of using the RMIC via these methods are covered in the following sections.
+ </para>
+
+ <section>
+ <title>Command Line Usage</title>
+ <para>
+ As this tool delegates compilation to the Sun RMIC tool, it accepts the same command line parameters. For more details please see the documentation for the Sun RMIC at <ulink url="http://java.sun.com/j2se/1.4.2/docs/tooldocs/tools.html#rmi" />. The following is an example of how this can be used:
+ </para>
+ <para>
+ An example of using the RMIC from the command line is: <code>java com.arjuna.common.tools.rmictool.RMICTool <parameters></code>
+ </para>
+ </section>
+
+ <section>
+ <title>ANT Usage</title>
+ <para>
+ The RMICTool is also a plug-in for the ANT RMIC task. To use the RMICTool, specify the fully qualified classname as the <varname>compiler</varname> attribute:
+ </para>
+ <screen>
+ <rmic compiler="com.arjuna.common.tools.rmictool.RMICTool"
+ classname="RMIObjectImpl"
+ base="build-dir" verify="true"
+ iiop="true" iiopopts="-poa"
+ classpathref="build.classpath"/>
+ </screen>
+ <note>
+ <para>
+ The RMICTool JAR file will only be found if it is specified in your system <varname>classpath</varname> or be located in the <filename>lib</filename> directory of your ANT distribution.
+ </para>
+ </note>
+ </section>
+ </section>
+</chapter>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-object_store_browser_window.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-object_store_browser_window.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list