JBoss JCA 1.0 Developer's Guide

You must have one of the following JDKs installed in order to build the project:

Remember to ensure that "javac" and "java" are in your path (or symlinked).

JAVA_HOME=/location/to/javahome
export JAVA_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
      

You must have Apache Ant 1.8.1+ installed on your system.

Remember to ensure that "ant" are in your path (or symlinked).

ANT_HOME=/location/to/anthome
export ANT_HOME

PATH=$ANT_HOME/bin:$PATH
export PATH
      

The JBoss JCA project uses Apache Ivy for dependency management.

Apache Ivy is automatically downloaded and included in the development environment, so no additional setup is required.

You must have Subversion 1.5+ installed on your system.

Remember to ensure that "svn" are in your path (or symlinked).

The anonymous SVN repository is located under:

svn co http://anonsvn.jboss.org/repos/jbossas/projects/jboss-jca/trunk/ jbossjca-trunk
      

The developer SVN repository is located under:

svn co https://svn.jboss.org/repos/jbossas/projects/jboss-jca/trunk/ jbossjca-trunk
      

We have the following modules for the project:

The purpose of the specification tests is to test our implementation against the actual specification text.

Each test can only depend on:

The test cases should be created in such a way such that they are easily identified by chapter, section and paragraph. For example:

org.jboss.jca.core.spec.chaper10.section3
      

The purpose of the JBoss specific interfaces tests is to test our specific interfaces.

Each test can depend on:

The test cases lives in a package that have a meaningful name of the component it tests. For example:

org.jboss.jca.core.workmanager
      

These test cases can use both the embedded JCA environment or be implemented as standard POJO based JUnit test cases.

The purpose of the JBoss specific implementation tests is to test our specific implementation. These tests should cover all methods are not exposed through the interface.

Each test can depend on:

The test cases lives in a package that have a meaningful name of the component it tests. For example:

org.jboss.jca.core.workmanager
      

These test cases can use both the embedded JCA environment or be implemented as standard POJO based JUnit test cases.

The integration tests simulate a real condition using a particular deployment artifacts packaged as resource adapters.

The resource adapters are created using either the main build environment or by using ShrinkWrap. Using resource adapters within the test cases will allow you to debug both the resource adapters themself or the JCA container.

The resource adapters represent the [given] facts of our BDD tests, the deployment of the resource adapters represent the [when] phase, while the [then] phase is verified by assertion.

Note that some tests consider an exception a normal output condition using the JUnit 4.x @Exception(expected = "SomeClass.class") annotation to identify and verify this situation.

We are mocking our input/output conditions in our unit tests using the Mockito framework to verify class and method behaviors.

An example:

@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"));
}
      

As you can see the BDD style respects the test method name and using the given-when-then sequence in order.

Checkstyle is a tool that verifies that the formatting of the source code in the project is consistent.

This allows for easier readability and a consistent feel of the project.

The goal is to have zero errors in the report. The checkstyle report is generated using

ant checkstyle
      

The report is generated into

reports/checkstyle
      

The home of checkstyle is located here: http://checkstyle.sourceforge.net/.

Findbugs is a tool that scans your project for bugs and provides reports based on its findings.

This tool helps lower of the number of bugs found in the JBoss JCA project.

The goal is to have zero errors in the report and as few exclusions in the filter as possible. The findbugs report is generated using

ant findbugs
      

The report is generated into

reports/findbugs
      

The home of findbugs is located here: http://findbugs.sourceforge.net/.

Cobertura generates a test suite matrix for your project which helps you identify where you need additional test coverage.

The reports that the tool provides makes sure that the JBoss JCA project has the correct test coverage.

The goal is to have as high code coverage as possible in all areas. The Cobertura report is generated using

ant cobertura
      

The report is generated into

reports/cobertura
      

The home of Cobertura is located here: http://cobertura.sourceforge.net/.

Tattletale generates reports about different quality matrix of the dependencies within the project.

The reports that the tool provides makes sure that the JBoss JCA project doesn't for example have cyclic dependencies within the project.

The goal is to have as no issues flagged by the tool. The Tattletale reports are generated using

ant tattletale
      

The reports are generated into

reports/tattletale
      

The home of Tattletale is located here: http://www.jboss.org/tattletale.

The Java Connector Architecture (JCA) metadata implement the metadata defined in the JCA specifications. We have metadata representing the following standards:

These metadata versions have a common super class

org.jboss.metadata.rar.spec.ConnectorMetaData
      

which allow the developer to for example query the version of the metadata.

The metadata is part of the

org.jboss.metadata.rar.jboss.RARDeploymentMetaData
      

structure.

The JBoss metadata implement JBoss specific extensions to the standard Java Connector Architecture metadata. We have metadata representing:

The metadata can be found in:

org.jboss.metadata.rar.jboss.JBossRAMetaData
      

The metadata is part of the

org.jboss.metadata.rar.jboss.RARDeploymentMetaData
      

structure.

TODO

The interface of the metadata repository is located in:

org.jboss.jca.core.api.MetaDataRepository
      

providing methods to query and update the repository.

The JBoss Microcontainer bean for the metadata repository can be defined as:

<bean name="MetaDataRepository" 
      interface="org.jboss.jca.core.api.MetaDataRepository" 
      class="org.jboss.jca.core.mdr.MetaDataRepositoryImpl">
</bean>