<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Developer Guide</title>
<date>2018-08-07</date>
</info>
<preface xml:id="_preface">
<title>Preface</title>
<section xml:id="_about">
<title>About IronJacamar</title>
<simpara>The goal of the IronJacamar project is to provide an implementation of the Java Connector Architecture 1.7 specification.</simpara>
<simpara>The specification can be found here: <link xl:href="http://www.jcp.org/en/jsr/detail?id=322">http://www.jcp.org/en/jsr/detail?id=322</link>.</simpara>
<simpara>The IronJacamar project is licensed under the GNU LESSER GENERAL PUBLIC LICENSE 2.1 (LGPL 2.1) license.</simpara>
</section>
<section xml:id="_whythename">
<title>Why IronJacamar ?</title>
<simpara>The Java EE Connector Architecture container can be viewed as a foundation inside an application server as it provides
connectivity to the other containers such that they can communicate with EISes.
Iron is often used as foundation in building houses too.</simpara>
<simpara>The Jacamar bird family which lives in Central and South America are glossy elegant birds with long bills  and tails.
Why we picked the Jacamar family is left as an exercise for the reader :)</simpara>
</section>
<section xml:id="_versions">
<title>Versions</title>
<simpara>This section contains the highlights of the IronJacamar releases.
A full description of each release can be found through our issue tracking system at <link xl:href="http://issues.jboss.org/browse/JBJCA">http://issues.jboss.org/browse/JBJCA</link>.</simpara>
<section xml:id="_versions_ironjacamar20">
<title>IronJacamar 2.0</title>
<itemizedlist>
<listitem>
<simpara>New architecture</simpara>
</listitem>
<listitem>
<simpara>Focus on EE 6+ interaction patterns</simpara>
</listitem>
<listitem>
<simpara>Similar configuration to IronJacamar 1.x deployments</simpara>
</listitem>
<listitem>
<simpara>High amount of reuse of IronJacamar 1.x components</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_versions_ironjacamar12">
<title>IronJacamar 1.2</title>
<simpara>Highlights as compared to IronJacamar 1.1:</simpara>
<itemizedlist>
<listitem>
<simpara>Support for graceful shutdown of <literal>ConnectionManager</literal> and <literal>WorkManager</literal></simpara>
</listitem>
<listitem>
<simpara>Support for connectable <literal>XAResource</literal>s</simpara>
</listitem>
<listitem>
<simpara>Support tracking of connection handles across transaction boundaries</simpara>
</listitem>
<listitem>
<simpara>Additional statistics for pools</simpara>
</listitem>
<listitem>
<simpara>Event tracer for easier debugging</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_versions_ironjacamar11">
<title>IronJacamar 1.1</title>
<simpara>Highlights as compared to IronJacamar 1.0:</simpara>
<itemizedlist>
<listitem>
<simpara>Java EE Connector Architecture 1.7 certified (standalone / Java EE7)</simpara>
</listitem>
<listitem>
<simpara>Lazy connection manager (JCA chapter 7.16)</simpara>
</listitem>
<listitem>
<simpara>Distributed work manager (JCA chapter 10.3.11)</simpara>
</listitem>
<listitem>
<simpara>Advanced pool capacity policies and flush strategies</simpara>
</listitem>
<listitem>
<simpara>Enhanced Arquillian integration</simpara>
</listitem>
<listitem>
<simpara>Eclipse development plugin</simpara>
</listitem>
<listitem>
<simpara>Enterprise Information System testing server</simpara>
</listitem>
<listitem>
<simpara>Resource adapter information tool</simpara>
</listitem>
<listitem>
<simpara>Migration tools</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_versions_ironjacamar10">
<title>IronJacamar 1.0</title>
<simpara>Highlights as compared to previous Java EE Connector Architecture containers inside JBoss Application Server:</simpara>
<itemizedlist>
<listitem>
<simpara>Java EE Connector Architecture 1.6 certified (standalone / Java EE6)</simpara>
</listitem>
<listitem>
<simpara>POJO container environment</simpara>
</listitem>
<listitem>
<simpara>New configuration schemas which focuses on usability</simpara>
</listitem>
<listitem>
<simpara>Fast XML and annotation parsing for quick deployment</simpara>
</listitem>
<listitem>
<simpara>Reauthentication support</simpara>
</listitem>
<listitem>
<simpara>Prefill support for security backed domains</simpara>
</listitem>
<listitem>
<simpara>Support for pool flushing strategies</simpara>
</listitem>
<listitem>
<simpara>Embedded environment for ease of development with Arquillian and ShrinkWrap integration</simpara>
</listitem>
<listitem>
<simpara>New management and statistics integration for components</simpara>
</listitem>
<listitem>
<simpara>Code generator for resource adapters</simpara>
</listitem>
<listitem>
<simpara>Validator tool for resource adapters</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_theteam">
<title>The team</title>
<simpara>Jesper Pedersen acts as the lead for the IronJacamar project.
He can be reached at jesper (dot) pedersen (at) ironjacamar (dot) org.</simpara>
<simpara>Stefano Maestri is a core developer on the IronJacamar project.
He can be reached at stefano (dot) maestri (at) ironjacamar (dot) org.</simpara>
<simpara>Lin Gao is a core developer on the IronJacamar project.
He can be reached at lin (dot) gao (at) ironjacamar (dot) org.</simpara>
<simpara>Tom Jenkinson is an advocate for the IronJacamar project.
He can be reached at tom (dot) jenkinson (at) ironjacamar (dot) org.</simpara>
<simpara>Johnaton Lee helps out in the IronJacamar community with identifying issues, and fixing them.
He can be reached at johnathonlee (at) ironjacamar (dot) org.</simpara>
<simpara>Tyronne Wickramarathne helps out in the IronJacamar community with identifying issues, and fixing them.
He can be reached at tyronne (at) ironjacamar (dot) org.</simpara>
</section>
<section xml:id="_thanksto">
<title>Thanks to</title>
<simpara>Adrian Brock, Carlo de Wolf, Gurkan Erdogdu, Bruno Georges, Paul Gier, Jason Greene, Stefan Guilhen,
Jonathan Halliday, Søren Hilmer, Ales Justin, Vicky Kak,  Aslak Knutsen, Sacha Labourey, Mark Little,
Alexey Loubyansky,  Patrick MacDonald, Scott Marlow, Shelly McGowan, Andrig Miller, Marcus Moyses,
John O&#8217;Hara, Weston Price, Andrew Lee Rubinger, Heiko Rupp, Anil Saldhana, Scott Stark, Clebert Suconic, Andy Taylor,
Vladimir Vasilev, Vladimir Rastseluev, Jeff Zhang, Tyronne Wickramarathne, Dimitris Andreadis,
Jeremy Whiting, Yang Yong and Leslie York.</simpara>
</section>
<section xml:id="_license">
<title>License</title>
<simpara>Copyright &#169; 2014 Red Hat, Inc.
and others.</simpara>
<simpara>The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA").</simpara>
<simpara>An explanation of CC-BY-SA is available at  <link xl:href="http://creativecommons.org/licenses/by-sa/3.0/">http://creativecommons.org/licenses/by-sa/3.0/</link>.
In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.</simpara>
<simpara>Red Hat, as the licensor of this document, waives the right to enforce,  and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent  permitted by applicable law.</simpara>
</section>
</preface>
<chapter xml:id="_introduction">
<title>Introduction</title>
<simpara>The Java Connector Architecture (JCA) defines a standard architecture for connecting the Java EE platform to
heterogeneous Enterprise Information Systems (EIS).
Examples of EISs include Enterprise Resource Planning (ERP), mainframe transaction processing (TP),
databases and messaging systems.</simpara>
<simpara>The connector architecture defines a set of scalable, secure, and transactional mechanisms that enable the integration
of EISs with application servers and enterprise applications.</simpara>
<simpara>The connector architecture also defines a Common Client Interface (CCI) for EIS access.
The CCI defines a client API for interacting with heterogeneous EISs.</simpara>
<simpara>The connector architecture enables an EIS vendor to provide a standard resource adapter for its EIS.
A resource adapter is a system-level software driver that is used by a Java application to connect to an EIS.
The resource adapter plugs into an application server and provides connectivity between the EIS, the application
server, and the enterprise application.
The resource adapter serves as a protocol adapter that allows any arbitrary EIS communication protocol to be used for
connectivity.
An application server vendor extends its system once to support the connector architecture and is then assured of
seamless connectivity to multiple EISs.
Likewise, an EIS vendor provides one standard resource adapter which has the capability to plug in to any application
server that supports the connector architecture.</simpara>
<section xml:id="_whatsnew">
<title>What&#8217;s New</title>
<section xml:id="_whatsnew_jca17">
<title>Java Connector Architecture 1.7</title>
<simpara>The Java Connector Architecture 1.7 specification adds the following areas:</simpara>
<itemizedlist>
<listitem>
<simpara>Adds an activation name for message endpoints to uniquely identify them</simpara>
</listitem>
<listitem>
<simpara>Deployment annotations for connection factories and administration objects</simpara>
</listitem>
</itemizedlist>
<note>
<simpara>The deployment annotations are only meant for developer usage, and should not be used in test or production environments.</simpara>
<simpara>The IronJacamar standalone and embedded distributions doesn&#8217;t support these annotations.</simpara>
</note>
</section>
<section xml:id="_whatsnew_jca16">
<title>Java Connector Architecture 1.6</title>
<simpara>The Java Connector Architecture 1.6 specification adds the following major areas:</simpara>
<itemizedlist>
<listitem>
<simpara>Ease of Development: The use of annotations reduces or completely eliminates the need to deal with a
deployment descriptor in many cases. The use of annotations also reduces the need
to keep the deployment descriptor synchronized with changes to source code.</simpara>
</listitem>
<listitem>
<simpara>Generic work context contract: A generic contract that enables a resource adapter
to control the execution context of a Work instance that it has submitted to the
application server for execution.</simpara>
</listitem>
<listitem>
<simpara>Security work context: A standard contract that enables a resource adapter to
establish security information while submitting a Work instance for execution to a
WorkManager and while delivering messages to message endpoints residing in
the application server.</simpara>
</listitem>
<listitem>
<simpara>Standalone Container Environment: A defined set of services that makes up a standalone
execution environment for resource adapters.</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_overview">
<title>Overview</title>
<simpara>The Java EE Connector Architecture features three different types of resource adapters</simpara>
<itemizedlist>
<listitem>
<simpara>Outbound: The resource adapter allows the application to communicate to the Enterprise Information System (EIS).</simpara>
</listitem>
<listitem>
<simpara>Inbound: The resource adapter allows messages to flow from the Enterprise Information System (EIS) to the application.</simpara>
</listitem>
<listitem>
<simpara>Bi-directional: The resource adapter features both an outbound and an inbound part.</simpara>
</listitem>
</itemizedlist>
<simpara>For more information about Java EE Connector Architecture see the specification.</simpara>
<section xml:id="_overview_outbound">
<title>Outbound resource adapter</title>
<simpara>The Java Connector Architecture specification consists of a number of outbound components:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/outbound.png"/>
</imageobject>
<textobject><phrase>outbound</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>The application uses the</simpara>
<itemizedlist>
<listitem>
<simpara>ConnectionFactory: The connection factory is looked up in Java Naming and Directory Interface (JNDI)
and is used to create a connection.</simpara>
</listitem>
<listitem>
<simpara>Connection: The connection contains the Enterprise Information System (EIS) specific operations.</simpara>
</listitem>
</itemizedlist>
<simpara>The resource adapter contains</simpara>
<itemizedlist>
<listitem>
<simpara>ManagedConnectionFactory: The managed connection factory creates managed connections.</simpara>
</listitem>
<listitem>
<simpara>ManagedConnection: The managed connection represents a physical connection to the target
Enterprise Information System (EIS). The managed connection notifies the application server
of events such as connection closed and connection error.</simpara>
</listitem>
</itemizedlist>
<simpara>IronJacamar - the application server - contains</simpara>
<itemizedlist>
<listitem>
<simpara>ConnectionManager: The connection manager handles all managed connections in regards to
pooling, transaction and security.</simpara>
</listitem>
<listitem>
<simpara>ConnectionEventListener: The connection event listener allows the connection manager to know
the status of each managed connection.</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_overview_inbound">
<title>Inbound resource adapter</title>
<simpara>The Java Connector Architecture specification consists of a number of inbound components:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/inbound.png"/>
</imageobject>
<textobject><phrase>inbound</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>The application uses the</simpara>
<itemizedlist>
<listitem>
<simpara>ActivationSpec: The activation specification specifies the different properties that the
application is looking for from the resource adapter and hence the Enterprise Information System (EIS).
This specification can be hidden from the user by a facade provided by the application server.</simpara>
</listitem>
</itemizedlist>
<simpara>The resource adapter contains</simpara>
<itemizedlist>
<listitem>
<simpara>ResourceAdapter: The resource adapter provides the activation point for inbound communication.</simpara>
</listitem>
<listitem>
<simpara>Resource adapter specific: The resource adapter specific code handles communication with the
Enterprise Information System (EIS) and deliver messages through the MessageEndpointFactory.</simpara>
</listitem>
</itemizedlist>
<simpara>IronJacamar - the application server - contains</simpara>
<itemizedlist>
<listitem>
<simpara>MessageEndpointFactory: The MessageEndpointFactory is registered with the ResourceAdapter instance
and creates the MessageEndpoint instances.</simpara>
</listitem>
<listitem>
<simpara>MessageEndpoint: The MessageEndpoint contains the actual message from the Enterprise Information System (EIS)
which the application uses. This could for example be a message driven Enterprise JavaBean (EJB/MDB).</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_project_resources">
<title>Project resources</title>
<itemizedlist>
<listitem>
<simpara>Web site: <link xl:href="http://www.ironjacamar.org">http://www.ironjacamar.org</link></simpara>
</listitem>
<listitem>
<simpara>Users forum: <link xl:href="https://groups.google.com/forum/#!forum/ironjacamar-users">https://groups.google.com/forum/#!forum/ironjacamar-users</link></simpara>
</listitem>
<listitem>
<simpara>developers forum: <link xl:href="https://groups.google.com/forum/#!forum/ironjacamar-developers">https://groups.google.com/forum/#!forum/ironjacamar-developers</link></simpara>
</listitem>
<listitem>
<simpara>Issue tracker: <link xl:href="https://github.com/ironjacamar/ironjacamar/issues">https://github.com/ironjacamar/ironjacamar/issues</link></simpara>
</listitem>
<listitem>
<simpara>Source code: <link xl:href="https://github.com/ironjacamar/ironjacamar">https://github.com/ironjacamar/ironjacamar</link></simpara>
</listitem>
<listitem>
<simpara>IRC channel: #ironjacamar on freenode.net</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_prerequisites">
<title>Prerequisites</title>
<section xml:id="_jdk">
<title>Java Development Kit (JDK)</title>
<simpara>You must have the following JDK installed in order to build the project:</simpara>
<itemizedlist>
<listitem>
<simpara>Sun JDK 1.8.x</simpara>
</listitem>
<listitem>
<simpara>OpenJDK 1.8.x</simpara>
</listitem>
</itemizedlist>
<simpara>Remember to ensure that "javac" and "java" are in your path (or symlinked).</simpara>
<screen>JAVA_HOME=/location/to/javahome
export JAVA_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH</screen>
</section>
<section xml:id="_gradle">
<title>Gradle</title>
<simpara>IronJacamar 2.x build is based on gradle. We are using gradle wrapper to avoid any needs of installation and
configuration of the toll.</simpara>
<note>
<simpara>To build only older version (1.x series) of the project you must have Apache Ant 1.9.4+installed on your system.</simpara>
<simpara>Please refer to specific version documentation for further and more detailed description.</simpara>
</note>
</section>
<section xml:id="_git">
<title>Git</title>
<simpara>You must have Git installed on your system.</simpara>
<simpara>Remember to ensure that "git" are in your path (or symlinked).</simpara>
</section>
</section>
<section xml:id="_obtainingthesource">
<title>Obtaining the source code</title>
<section xml:id="_forking">
<title>Forking the repository</title>
<simpara>The IronJacamar repository is located at:</simpara>
<screen>https://github.com/ironjacamar/ironjacamar</screen>
<simpara>Press the "Fork" button in order to fork the repository to your own GitHub account.</simpara>
<simpara>Clone your repository to your machine using</simpara>
<screen>git clone git@github.com:&lt;your_account&gt;/ironjacamar.git</screen>
<simpara>Next add the upstream repository as a remote location:</simpara>
<screen>cd ironjacamar
git remote add upstream git@github.com:ironjacamar/ironjacamar.git</screen>
</section>
<section xml:id="_gitbranches">
<title>Git branches</title>
<simpara>We have the following branches for the project:</simpara>
<itemizedlist>
<listitem>
<simpara>master</simpara>
<simpara>The head of development targeting the next upcoming release. (2.0)</simpara>
</listitem>
<listitem>
<simpara>1.0</simpara>
<simpara>The development targeting the IronJacamar 1.0 releases.</simpara>
</listitem>
<listitem>
<simpara>1.1</simpara>
<simpara>The development targeting the IronJacamar 1.1 releases.</simpara>
</listitem>
<listitem>
<simpara>1.2</simpara>
<simpara>The development targeting the IronJacamar 1.2 releases.</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_compiling">
<title>Compiling the source code</title>
<simpara>In order to build IronJacamar you should execute from project&#8217;s main directory:</simpara>
<screen>./gradlew &lt;task&gt;</screen>
<simpara>Task is option and if you don&#8217;t specify it gradle would execute default task of the project which is "build"</simpara>
<simpara>For a complete list of available tasks and their description just run</simpara>
<screen>./gradlew tasks</screen>
</section>
<section xml:id="_creating_a_patch">
<title>Creating a patch</title>
<simpara><emphasis role="strong">NOTE: A prerequisite to submit a patch through github Pull Request is to sign Contribution Licence Agreement here: <link xl:href="https://cla.jboss.org/contributions/index.seam">https://cla.jboss.org/contributions/index.seam</link></emphasis></simpara>
<simpara>Our user guide explains in the "I would like to implement a feature" section how to get  started on a writing a new feature or submitting a patch to the project.</simpara>
<simpara>You should develop your feature on a Git branch using</simpara>
<screen>git checkout -b &lt;feature_name&gt;</screen>
<simpara>Once you are done you will need to rebase your work with the latest master.</simpara>
<screen>git fetch upstream
git rebase -i upstream/master</screen>
<simpara>You will need to resolve any conflicts of course.
Note, that all pull requests must be rebased against upstream master in order to get merged.</simpara>
<simpara>Please verify you are able to build the project, all tests pass and the checkstyle is respected. Just run</simpara>
<screen>./gradlew --info</screen>
<simpara>It should build w/o any error.</simpara>
<simpara>Then push the feature to your repository</simpara>
<screen>git push origin &lt;feature_name&gt;</screen>
<simpara>Go to your account on GitHub.com and submit a pull request via the "Pull request" button</simpara>
<screen>https://www.github.com/&lt;your_account&gt;/ironjacamar</screen>
<simpara>Remember to select the correct branch, fill in the subject with a short description of the feature, and fill in the description with the full description of the feature.</simpara>
<simpara>If your feature / bug-fix applies to multiple branches you will need to submit multiple pull requests - one pull request per branch.</simpara>
<simpara>Remember your commit message should contain the issue ID and its description previously created in our issue tracker.
Please refer to issue tracking chapter of this document for more information on how to create and manage issues.</simpara>
</section>
<section xml:id="_continuous_integration">
<title>Continuous Integration</title>
<simpara>When you send a PR Travis CI (<link xl:href="https://travis-ci.org">https://travis-ci.org</link>) will automatically build the project.</simpara>
<simpara>During the build, Travis update the status of the commits to one of:</simpara>
<itemizedlist>
<listitem>
<simpara>a warning that the build is still running.</simpara>
</listitem>
<listitem>
<simpara>that the pull request should be merged with caution because the build failed.</simpara>
</listitem>
<listitem>
<simpara>that the pull request can be merged safely because the build was successful.</simpara>
</listitem>
</itemizedlist>
<simpara>Travis CI builds a pull request when it is first opened, and when commits are added to the pull request .</simpara>
</section>
<section xml:id="_code_review_and_merging">
<title>Code review and merging</title>
<simpara>Finally your PR will be reviewed by a core developer and merged if everything is ok, commented to be refined otherwise.</simpara>
<simpara>Don&#8217;t forget PR and issues are not forums and you will be encouraged discussing design and details through forums, while issue/PRs comments
should be used only for specific details or referring to specific line of code.</simpara>
</section>
</chapter>
<chapter xml:id="_releases">
<title>Releases</title>
<simpara>The chapter describes the various releases and their exit criteria.</simpara>
<section xml:id="_releases_overview">
<title>Overview</title>
<simpara>Each release is labelled with a version number and an identifier.</simpara>
<screen>ironjacamar-&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;[.&lt;identifier&gt;]</screen>
<simpara>where</simpara>
<itemizedlist>
<listitem>
<simpara>Major: The major version number. Signifies major changes in the implementation.</simpara>
</listitem>
<listitem>
<simpara>Minor: The minor version number. Signifies functional changes to a major version.</simpara>
</listitem>
<listitem>
<simpara>Patch: The patch version number. Signifies a binary compatible change to a minor version.</simpara>
</listitem>
<listitem>
<simpara></simpara>
<itemizedlist>
<listitem>
<simpara>None / Final: Stable release</simpara>
</listitem>
<listitem>
<simpara>CR: Candidate for Release quality. The implementation is functional complete.</simpara>
</listitem>
<listitem>
<simpara>Beta: Beta quality. The implementation is almost functional complete.</simpara>
</listitem>
<listitem>
<simpara>Alpha: Alpha quality. The implementation is a snapshot of the development.</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section xml:id="_releases_versioning">
<title>Versioning</title>
<simpara>Each release will contain a version number which relates to the  feature branch where it was created.</simpara>
<section xml:id="_releases_versioning_major">
<title>Major</title>
<simpara>A Major version identifier signifies major changes in the implementation such as a change in the architecture.</simpara>
<simpara>The features between major versions can be a lot different, and therefore feature regressions may appear.</simpara>
<simpara>A Major version will most likely also mean updates to the configuration and required metadata files for deployments.</simpara>
</section>
<section xml:id="_releases_versioning_minor">
<title>Minor</title>
<simpara>A Minor version identifier signifies functional changes to a Major release.</simpara>
<simpara>This means that new features have been added to the Major release, and hence may have new configuration options and integration points.</simpara>
<simpara>The release is binary compatible to the previous releases -  for example <literal>1.0</literal> vs. <literal>1.1</literal>.</simpara>
</section>
<section xml:id="_releases_versioning_patch">
<title>Patch</title>
<simpara>A Patch version identifier signifies a binary compatible update to one or more components in a Minor release.</simpara>
<simpara>This means that one or more bug fixes to existing components have been integrated in the branch in question.</simpara>
<simpara>The release is binary compatible to the previous releases -  for example <literal>1.0.0</literal> vs. <literal>1.0.1</literal>.</simpara>
</section>
</section>
<section xml:id="_releases_identifiers">
<title>Identifiers</title>
<simpara>Each release will contain an identifier which relates to the release quality.</simpara>
<section xml:id="_releases_alpha">
<title>Alpha releases</title>
<simpara>An Alpha release is a snapshot of the main development branch which likely will contain new features.</simpara>
<warning>
<literallayout class="monospaced">Alpha releases are NOT production quality</literallayout>
</warning>
<simpara>An Alpha release is made each month (time-boxed) unless the branch is using an identifier as  Beta or higher.</simpara>
<simpara>The exit criteria for an Alpha release is that the main test suite is passing.</simpara>
</section>
<section xml:id="_releases_beta">
<title>Beta releases</title>
<simpara>A Beta release contains major features that are considered almost functional complete.
This doesn&#8217;t mean however that all aspects of each feature is complete and therefore not all options will be active.</simpara>
<warning>
<literallayout class="monospaced">Beta releases are NOT production quality</literallayout>
</warning>
<simpara>A Beta release will be made once one or more features are almost functional complete and therefore Beta releases aren&#8217;t time-boxed, but feature-boxed instead.</simpara>
<simpara>The exit criteria for a Beta release is that all test suites are passing.</simpara>
</section>
<section xml:id="_releases_cr">
<title>Candidate for Release releases</title>
<simpara>A Candidate for Release is considered functional complete and candidate for being  promoted to a Final release.</simpara>
<warning>
<literallayout class="monospaced">Candidate for Release releases are NOT production quality</literallayout>
</warning>
<simpara>A Candidate for Release focuses on functionality, but they are time-boxed to a maximum of two weeks between each release.</simpara>
<simpara>The exit criteria for a Candidate for Release release is that all test suites are passing.</simpara>
</section>
<section xml:id="_releases_final">
<title>Final releases</title>
<simpara>A Final release is considered feature complete and stable.</simpara>
<simpara>Typically only one Final release will be released from each branch, unless critical or blocker issues are found in the release.
Patch releases will be available from our source control system as tags.</simpara>
<simpara>The exit criteria for a Final release is that all test suites are passing.</simpara>
</section>
</section>
</chapter>
<chapter xml:id="_issuetracking">
<title>Issue tracking</title>
<section xml:id="_location">
<title>Location</title>
<simpara>IronJacamar 2.x series is using Github issue tracker located at <link xl:href="https://github.com/ironjacamar/ironjacamar/issues">https://github.com/ironjacamar/ironjacamar/issues</link></simpara>
<simpara>There is also a JIRA issue tracking for bugs impacting older releases. It is located at <link xl:href="http://issues.jboss.org/browse/JBJCA">http://issues.jboss.org/browse/JBJCA</link></simpara>
<note>
<simpara>For further informations on how Jira issue tracking is organized and how to use it please refer to 1.x documentation</simpara>
</note>
</section>
<section xml:id="_labels">
<title>Labels</title>
<simpara>Github issue tracking uses a label based system to tag issues. IronJacamar is using different labels to identify:</simpara>
<itemizedlist>
<listitem>
<simpara>Black labels: Components impacted by the issue</simpara>
</listitem>
<listitem>
<simpara>Yellow labels: Issue category</simpara>
</listitem>
<listitem>
<simpara>Blue labels: Issue priority</simpara>
</listitem>
<listitem>
<simpara>Violet labels: rejecting reasons</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_components">
<title>Components (black labels)</title>
<simpara>The project is divided into the following components:</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>Project components</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Label name</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>API</simpara></entry>
<entry align="left" valign="top"><simpara>Public API</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Build</simpara></entry>
<entry align="left" valign="top"><simpara>The build environment for the project.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Common</simpara></entry>
<entry align="left" valign="top"><simpara>Common interfaces and classes that are shared between multiple components.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Core</simpara></entry>
<entry align="left" valign="top"><simpara>The core implementation of the project.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Documentation</simpara></entry>
<entry align="left" valign="top"><simpara>The documentation (Users Guide / Developers Guide) for the project.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Deployer</simpara></entry>
<entry align="left" valign="top"><simpara>The deployers for the project.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Embedded</simpara></entry>
<entry align="left" valign="top"><simpara>The embedded IronJacamar container.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>JDBC</simpara></entry>
<entry align="left" valign="top"><simpara>A JDBC resource adapter.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Performance</simpara></entry>
<entry align="left" valign="top"><simpara>Performance related work.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Standalone</simpara></entry>
<entry align="left" valign="top"><simpara>The standalone IronJacamar distribution.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Test Suite</simpara></entry>
<entry align="left" valign="top"><simpara>The IronJacamar test suite.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Tools</simpara></entry>
<entry align="left" valign="top"><simpara>Tools used related work.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Validator</simpara></entry>
<entry align="left" valign="top"><simpara>The resource adapter validator.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_categories">
<title>Categories (yellow labels)</title>
<simpara>The system contains the following categoies:</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>Issues categories</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Label name</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>Feature Request</simpara></entry>
<entry align="left" valign="top"><simpara>Request for a feature made by the community.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Bug</simpara></entry>
<entry align="left" valign="top"><simpara>Software defect in the project.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Task</simpara></entry>
<entry align="left" valign="top"><simpara>Development task created by a member of the team.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Release</simpara></entry>
<entry align="left" valign="top"><simpara>Issue which holds informations about a release.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Component Update</simpara></entry>
<entry align="left" valign="top"><simpara>Identifies a thirdparty library dependency.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_priorities">
<title>Priorities (blue labels)</title>
<simpara>All issues are assigned one of the following priorities:</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>Issues Priorities</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Label name</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>Blocker</simpara></entry>
<entry align="left" valign="top"><simpara>An issue that needs to be fixed before the release.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Critical</simpara></entry>
<entry align="left" valign="top"><simpara>An issue that is critical for the release.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Major</simpara></entry>
<entry align="left" valign="top"><simpara>The default priority for an issue.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Minor</simpara></entry>
<entry align="left" valign="top"><simpara>An issue that is optional for a release.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_rejecting">
<title>Rejecting reasons (violet labels)</title>
<simpara>When an issue is rejected it&#8217;s closed and tagged with one of these labels. A comment should explain why it has been rejected.</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>Rejecting reasons</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Label name</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>wontfix</simpara></entry>
<entry align="left" valign="top"><simpara>The issue will not be fixed because it&#8217;s not a bug and described behaviour is expected,</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>duplicated</simpara></entry>
<entry align="left" valign="top"><simpara>The issue is duplicated. A link to original issue is provided in closing comment.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>cannot reproduce</simpara></entry>
<entry align="left" valign="top"><simpara>The issue is not reproducible with provided information and description.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_lifecycle">
<title>Life cycle</title>
<simpara>All issues have the following life cycle:</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>JIRA Lifecycle</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry align="left" valign="top">Lifecycle</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>Open</simpara></entry>
<entry align="left" valign="top"><simpara>An issue currently not implemented.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>Closed</simpara></entry>
<entry align="left" valign="top"><simpara>An issue that has been resolved. It will be included in target release.</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</chapter>
<chapter xml:id="_testing">
<title>Testing</title>
<section xml:id="_testinggoals">
<title>Overall goals</title>
<simpara>The overall goals of our test environment is to execute tests that ensure that we have full coverage of the JCA specification as well as our implementation.</simpara>
<simpara>The full test suite runs every time you build the project.</simpara>
<screen>./gradlew --info</screen>
<simpara>You can run just testsuite w/o remake a full build</simpara>
<screen>---
./gradlew test --info
---</screen>
<simpara>There is few special tests running multiple instance of embedded environment excluded by default build. You can run also them with</simpara>
<screen>---
./ghradlew test --info -PmiTest=true
---</screen>
<simpara>A single test case can be executed using</simpara>
<screen>./gradlew --info test --tests &lt;testname&gt;</screen>
<simpara>where &lt;testname&gt; is a fully qualified name of test class
Note you can also use * operator to filter test name</simpara>
<screen>./gradlew --info test --tests *JGroups*</screen>
<simpara>You can also run test in debug mode and attach your favorite remote debugger on port 5005 running</simpara>
<screen>./gradlew --info -Dtest.debug</screen>
<simpara>Of course you can combine above options for example to debug a single test case.</simpara>
</section>
<section xml:id="_style">
<title>Testing principle and style</title>
<simpara>Our tests follow the Behavior Driven Development (BDD) technique.
In BDD you focus on specifying the behaviors of a class and write code (tests) that verify that behavior.</simpara>
<simpara>You may be thinking that BDD sounds awfully similar to Test Driven Development (TDD).  In some ways they are similar: they both encourage writing the tests first and to provide full coverage of the  code.
However, TDD doesn&#8217;t really provide a guide on which kind of tests you should be writing.</simpara>
<simpara>BDD provides you with guidance on how to do testing by focusing on what the behavior of a class is supposed to be.
We introduce BDD to our testing environment by extending the standard JUnit 4.x test framework with BDD capabilities using assertion and mocking frameworks.</simpara>
<simpara>The BDD tests should</simpara>
<itemizedlist>
<listitem>
<simpara>Clearly define <literal>given-when-then</literal> conditions</simpara>
</listitem>
<listitem>
<simpara>The method name defines what is expected: f.ex. shouldReturnFalseIfMethodXIsCalledWithNullString()</simpara>
</listitem>
<listitem>
<simpara>Easy to read the assertions by using <link xl:href="http://code.google.com/p/hamcrest/">Hamcrest Matchers</link></simpara>
</listitem>
<listitem>
<simpara>Use <literal>given</literal> facts whenever possible to make the test case more readable. It could be the name of the deployed resource adapter, or using the  <link xl:href="http://mockito.googlecode.com/svn/branches/1.8.0/javadoc/org/mockito/BDDMockito.html"> BDD Mockito class</link> to mock the fact.</simpara>
</listitem>
</itemizedlist>
<simpara>We are using two different kind of tests:</simpara>
<itemizedlist>
<listitem>
<simpara>Integration Tests: The goal of these test cases is to validate the whole process of deployment, and interacting with a sub-system by simulating a critical condition.</simpara>
</listitem>
<listitem>
<simpara>Unit Tests: The goal of these test cases is to stress test some internal behaviour by mocking classes to perfectly reproduce conditions to test.</simpara>
</listitem>
</itemizedlist>
<section xml:id="_integration">
<title>Integration Tests</title>
<simpara>The integration tests simulate a real condition using particular deployment artifacts packaged as resource adapters.</simpara>
<simpara>The resource adapters are created using either the main build environment or by using  <link xl:href="http://community.jboss.org/wiki/ShrinkWrap">ShrinkWrap</link>.
Using resource adapters within the test cases will allow you to debug both the resource adapters themself or the JCA container.</simpara>
<simpara>The resource adapters represent the <xref linkend="given"/>
 facts of our BDD tests,  the deployment of the resource adapters represent the <xref linkend="when"/>
 phase,  while the <xref linkend="then"/>
 phase is verified by assertion.</simpara>
<simpara>Note that some tests consider an exception a normal output condition using the JUnit 4.x  <literal>@Exception(expected = "SomeClass.class")</literal> annotation to identify and verify this situation.</simpara>
<simpara>This kind of tests run inside our embedded environment and creating deployment descriptor with our builder.
Few custom annotation make embedded environment start/deploy/undeploy/stop in test calsses very simple and human readable.
A test class look like this:</simpara>
<screen>package org.ironjacamar.core.workmanager;

import org.ironjacamar.embedded.Configuration;
import org.ironjacamar.embedded.Deployment;
import org.ironjacamar.embedded.dsl.resourceadapters20.api.ResourceAdaptersDescriptor;
import org.ironjacamar.embedded.junit4.AllChecks;
import org.ironjacamar.embedded.junit4.IronJacamar;
import org.ironjacamar.embedded.junit4.PostCondition;
import org.ironjacamar.embedded.junit4.PreCondition;
import org.ironjacamar.rars.ResourceAdapterFactory;
import org.ironjacamar.rars.wm.WorkConnection;
import org.ironjacamar.rars.wm.WorkConnectionFactory;

import javax.annotation.Resource;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;

import org.junit.Test;
import org.junit.runner.RunWith;

import static org.junit.Assert.assertNotNull;

/**
 * Basic WorkManager test case
 * @author &lt;a href="mailto:jesper.pedersen@ironjacamar.org"&gt;Jesper Pedersen&lt;/a&gt;
 */
@RunWith(IronJacamar.class)
@Configuration(full = true)
@PreCondition(condition = AllChecks.class)
@PostCondition(condition = AllChecks.class)
public class WorkManagerTestCase
{
   /** The user transaction */
   @Resource(mappedName = "java:/eis/WorkConnectionFactory")
   private WorkConnectionFactory wcf;

   /**
    * The resource adapter
    * @throws Throwable In case of an error
    */
   @Deployment(order = 1)
   private ResourceAdapterArchive createResourceAdapter() throws Throwable
   {
      return ResourceAdapterFactory.createWorkRar();
   }

   /**
    * The activation
    * @throws Throwable In case of an error
    */
   @Deployment(order = 2)
   private ResourceAdaptersDescriptor createActivation() throws Throwable
   {
      return ResourceAdapterFactory.createWorkDeployment(null);
   }

   /**
    * Deployment
    * @throws Throwable In case of an error
    */
   @Test
   public void testDeployment() throws Throwable
   {
      assertNotNull(wcf);

      WorkConnection wc = wcf.getConnection();
      assertNotNull(wc);

      wc.close();
   }
}</screen>
<simpara>While ResourceAdapterFactory methods invoked like this</simpara>
<screen> /**
    * Create the work.rar
    *
    * @return The resource adapter archive
    */
   public static ResourceAdapterArchive createWorkRar()
   {
      org.jboss.shrinkwrap.descriptor.api.connector16.ConnectorDescriptor raXml = Descriptors
            .create(org.jboss.shrinkwrap.descriptor.api.connector16.ConnectorDescriptor.class, "ra.xml").version("1.6");

      org.jboss.shrinkwrap.descriptor.api.connector16.ResourceadapterType rt = raXml.getOrCreateResourceadapter()
            .resourceadapterClass(WorkResourceAdapter.class.getName());
      org.jboss.shrinkwrap.descriptor.api.connector16.OutboundResourceadapterType ort = rt
            .getOrCreateOutboundResourceadapter().transactionSupport("NoTransaction").reauthenticationSupport(false);
      org.jboss.shrinkwrap.descriptor.api.connector16.ConnectionDefinitionType cdt = ort.createConnectionDefinition()
            .managedconnectionfactoryClass(WorkManagedConnectionFactory.class.getName())
            .connectionfactoryInterface(WorkConnectionFactory.class.getName())
            .connectionfactoryImplClass(WorkConnectionFactoryImpl.class.getName())
            .connectionInterface(WorkConnection.class.getName())
            .connectionImplClass(WorkConnectionImpl.class.getName());

      ResourceAdapterArchive raa = ShrinkWrap.create(ResourceAdapterArchive.class, "work.rar");

      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, "work.jar");
      ja.addPackages(true, WorkConnection.class.getPackage());

      raa.addAsLibrary(ja);
      raa.addAsManifestResource(new StringAsset(raXml.exportAsString()), "ra.xml");

      return raa;
   }

   /**
    * Create the work.rar deployment
    *
    * @param bc The BootstrapContext name; &lt;code&gt;null&lt;/code&gt; if default
    * @return The resource adapter descriptor
    */
   public static ResourceAdaptersDescriptor createWorkDeployment(String bc)
   {
      ResourceAdaptersDescriptor dashRaXml = Descriptors.create(ResourceAdaptersDescriptor.class, "work-ra.xml");

      ResourceAdapterType dashRaXmlRt = dashRaXml.createResourceAdapter().archive("work.rar");
      if (bc != null)
         dashRaXmlRt.bootstrapContext(bc);
      ConnectionDefinitionsType dashRaXmlCdst = dashRaXmlRt.getOrCreateConnectionDefinitions();
      org.ironjacamar.embedded.dsl.resourceadapters20.api.ConnectionDefinitionType dashRaXmlCdt = dashRaXmlCdst
            .createConnectionDefinition().className(WorkManagedConnectionFactory.class.getName())
            .jndiName("java:/eis/WorkConnectionFactory").id("WorkConnectionFactory");

      org.ironjacamar.embedded.dsl.resourceadapters20.api.PoolType dashRaXmlPt = dashRaXmlCdt.getOrCreatePool()
            .minPoolSize(0).initialPoolSize(0).maxPoolSize(10);

      return dashRaXml;
   }</screen>
</section>
<section xml:id="_unit">
<title>Unit Tests</title>
<simpara>We are mocking our input/output conditions in our unit tests using the <link xl:href="http://mockito.googlecode.com">Mockito</link> framework to verify class and method behaviors.</simpara>
<simpara>An example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void printFailuresLogShouldReturnNotEmptyStringForWarning() throws Throwable
{
   //given
   RADeployer deployer = new RADeployer();
   File mockedDirectory = mock(File.class);
   given(mockedDirectory.exists()).willReturn(false);

   Failure failure = mock(Failure.class);
   given(failure.getSeverity()).willReturn(Severity.WARNING);

   List failures = Arrays.asList(failure);
   FailureHelper fh = mock(FailureHelper.class);
   given(fh.asText((ResourceBundle) anyObject())).willReturn("myText");

   deployer.setArchiveValidationFailOnWarn(true);

   //when
   String returnValue = deployer.printFailuresLog(null, mock(Validator.class),
                                                  failures, mockedDirectory, fh);

   //then
   assertThat(returnValue, is("myText"));
}</programlisting>
<simpara>As you can see the BDD style respects the test method name and using the <literal>given-when-then</literal> sequence in order.</simpara>
</section>
</section>
<section xml:id="_qa">
<title>Quality Assurance</title>
<simpara>In addition to the test suite the IronJacamar project deploys various tools to increase the stability of the project.</simpara>
<simpara>The following sections will describe each of these tools.</simpara>
<section xml:id="_checkstyle">
<title>Checkstyle</title>
<simpara>Checkstyle is a tool that verifies that the formatting of the source code in the project is consistent.</simpara>
<simpara>This allows for easier readability and a consistent feel of the project.</simpara>
<simpara>The goal is to have zero errors in the report.
The checkstyle report is generated on every build and can be found under each module&#8217;s build directory.</simpara>
</section>
<section xml:id="_jacoco">
<title>JaCoCo</title>
<simpara>JaCoCo generates a test suite matrix for your project which helps you identify where you need additional test coverage.</simpara>
<simpara>The reports that the tool provides makes sure that the IronJacamar project has the correct test coverage.</simpara>
<simpara>The goal is to have as high code coverage as possible in all areas.
The JaCoco report is generated at every build</simpara>
<simpara>The report is generated into</simpara>
<screen>testsuite/build/reports/jacoco</screen>
<simpara>The home of JaCoCo is located here: <link xl:href="http://www.eclemma.org/jacoco/">http://www.eclemma.org/jacoco/</link>.</simpara>
</section>
</section>
<section xml:id="_performance">
<title>Performance testing</title>
<simpara>Performance testing can identify areas that need to be improved or completely replaced.</simpara>
<section xml:id="_jprofiler">
<title>JProfiler</title>
<simpara>Insert the following line in <literal>run.sh</literal> or <literal>run.bat</literal>:</simpara>
<screen>-agentpath:&lt;path&gt;/jprofiler6/bin/linux-x64/libjprofilerti.so=port=8849</screen>
<simpara>where the Java command is executed.</simpara>
<simpara>The home of JProfiler is located here: <link xl:href="http://www.ej-technologies.com/products/jprofiler/overview.html">http://www.ej-technologies.com/products/jprofiler/overview.html</link>.</simpara>
</section>
<section xml:id="_oprofile">
<title>OProfile</title>
<simpara>OProfile can give a detailed overview of applications running on the machine, including Java program running with OpenJDK.</simpara>
<simpara>The home of OProfile is located here: <link xl:href="http://oprofile.sourceforge.net">http://oprofile.sourceforge.net</link>.</simpara>
<section xml:id="_oprofile_install">
<title>Installation</title>
<simpara>Enable the Fedora debug repo:</simpara>
<screen>/etc/yum.repos.d/fedora.repo

[fedora-debuginfo]
name=Fedora $releasever - $basearch - Debug
failovermethod=priority
mirrorlist=https://mirrors.fedoraproject.org/metalink?repo=fedora-debug-$releasever&amp;arch=$basearch
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-$basearch</screen>
<simpara>Install:</simpara>
<screen>dnf install -y oprofile oprofile-jit
dnf install -y yum-plugin-auto-update-debug-info
dnf install -y java-1.6.0-openjdk-debuginfo</screen>
<simpara>If you are using Fedora 21 or older, you need to use yum instead of dnf to install OProfile:</simpara>
<screen>yum install -y oprofile oprofile-jit
yum install -y yum-plugin-auto-update-debug-info
yum install -y java-1.6.0-openjdk-debuginfo</screen>
</section>
<section xml:id="_oprofile_running">
<title>Running</title>
<simpara>Insert the following line in <literal>run.sh</literal> or <literal>run.bat</literal>:</simpara>
<screen>-agentpath:/usr/lib64/oprofile/libjvmti_oprofile.so</screen>
<simpara>for 64bit JVMs or</simpara>
<screen>-agentpath:/usr/lib/oprofile/libjvmti_oprofile.so</screen>
<simpara>for 32 bit JVMs where the Java command is executed.</simpara>
<simpara>Now execute:</simpara>
<screen>opcontrol --no-vmlinux
opcontrol --start-daemon</screen>
<simpara>and use the following commands:</simpara>
<screen>opcontrol --start # Starts profiling
opcontrol --dump  # Dumps the profiling data out to the default file
opcontrol --stop  # Stops profiling</screen>
<simpara>Once you are done execute:</simpara>
<screen>opcontrol --shutdown  # Shuts the daemon down</screen>
<simpara>A report can be generated by:</simpara>
<screen>opreport -l --output-file=&lt;filename&gt;</screen>
<simpara>Remember that this is system wide profiling, so make sure that only the services that you want included are running.</simpara>
<simpara>More information is available at <link xl:href="http://oprofile.sourceforge.net/doc/index.html">http://oprofile.sourceforge.net/doc/index.html</link>.</simpara>
</section>
</section>
<section xml:id="_performance_test_suite">
<title>Performance test suite</title>
<simpara>TODO</simpara>
</section>
</section>
</chapter>
<chapter xml:id="_standalone">
<title>Standalone</title>
<section xml:id="_standaloneoverview">
<title>Overview</title>
<simpara>The standalone IronJacamar container implements Chapter 3 Section 5 of the  JCA 1.6 specification which defines a standalone JCA environment.</simpara>
<simpara>The standalone container has the following layout:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/bin/</literal></simpara>
<simpara>contains the run scripts and the SJC kernel.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/config/</literal></simpara>
<simpara>contains the configuration of the container.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/deploy/</literal></simpara>
<simpara>contains the user deployments.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/doc/</literal></simpara>
<simpara>contains the documentation.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/lib/</literal></simpara>
<simpara>contains all the libraries used by the container.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/log/</literal></simpara>
<simpara>contains the log files.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/system/</literal></simpara>
<simpara>contains system deployments files.</simpara>
</listitem>
<listitem>
<simpara><literal>$IRON_JACAMAR_HOME/tmp/</literal></simpara>
<simpara>contains temporary files.</simpara>
</listitem>
</itemizedlist>
<simpara>To start the container execute the following</simpara>
<screen>cd $IRON_JACAMAR_HOME/bin
./run.sh</screen>
<simpara>.</simpara>
</section>
<section xml:id="_jcasjc">
<title>IronJacamar/SJC</title>
<warning>
<literallayout class="monospaced">This standalone configuration is for development purposes only.</literallayout>
</warning>
<simpara>The IronJacamar/SJC uses the Fungal kernel for its run-time environment.</simpara>
<simpara>The homepage for the Fungal is <link xl:href="http://jesperpedersen.github.com/fungal">http://jesperpedersen.github.com/fungal</link></simpara>
<simpara>SJC is short for "Simple JCA Container".</simpara>
</section>
</chapter>
</book>