Source

Firstly, check out the source from the git repository.

git clone https://git-wip-us.apache.org/repos/asf/qpid-broker-j.git qpid-broker-j

Prerequisites

Java

The build requires a Java 8 or later. You should set the JAVA_HOME environment variable and include its bin directory in your PATH.

Check it's OK by executing the following at your command prompt.

java -version

Maven

The build requires a Maven version of 3.0.0 or later.  You should set the M2_HOME environment variable and include its bin directory in your PATH.

Check it's OK by executing the following at your command prompt.

mvn --version

Qpid Maven Structure

For complete reference and documentation on Maven please visit the following online resources.

Apache Maven Project

Maven: The Complete Reference by Sonatype

Project Object Model (POM)

Each Qpid java module has its own POM file (pom.xml) located in its root directory.

This file defines the modules version, dependencies and project inheritence as well as the configuration of the relative maven plugins specific to this module.  

At present we have 2 high level "parent" modules that serve as the grandparent and parent of all the java modules in the project.

Maven Commands

Here is a quick reference guide outlining some of the maven commands you can run and what the outcome will be.

Please visit Introduction To The Maven Lifecycle reference guide for full details on all the maven lifecycle phases.

Maven Profiles

Maven profiles are used to allow set configuration to be enables easily at the command line using the -P option.   If no profile is selected, java-mms-1.0 is run by default.

for e.g.

mvn verify -Pjava-bdb.1-0

Please visit Introduction To Maven Profiles for full details on the use of profiles in a maven build.

Maven Build Output

By default the build output for a maven module will appear in the modules "target" directory:

for e.g. the broker core module output appears in:

broker-core/target

Depending on the goals specified in the last build, one or all of the following can be found in the "target" directory.

The releaseable Client and Broker binary packages can be found in the following locations locally if required for testing.

Broker

broker/target/qpid-broker-VERSION-bin.tar.gz

Once you have this then follow the Java Broker installation instructions.

Client

client/target/qpid-client-VERSION-bin.tar.gz

Once you have this then refer to the JMS client documentation.

Example Maven Commands

Here are some example Maven build commands that you may find usefull.

Clean previous builds output and install all modules to local repository without running any of the unit or system tests.

mvn clean install -DskipTests

Clean previous builds output and installs all modules to the local repository after running all the tests using the Java BDB 1-0 profile

mvn clean install -Pjava-bdb.1-0

Clean previous builds output and installs all modules to the local repository after running all the tests using the Java MMS 0-9 profile

mvn clean install -Pjava-mms.0-9 -DenableAmqp0-x

Perform a subset of the QA (int or sys tests) on the packaged release artifacts

mvn verify -Dtest=TestNamePattern* -DfailIfNoTests=false

Execute the unit tests and then produce the code coverage report

mvn test jacoco:report

Joram JMS Testsuite

The Joram JMS Testsuite is integrated into the Maven build but is disabled by default.  It allows the Joram JMS test suite to executed, using the specified Qpid JMS client, against the Java Broker.  The Java Broker must be running already.

The following clients are supported:

• qpid-jms-client - Qpid Client AMQP 1.0
• qpid-amqp-1-0-client-jms - the proof of concept Qpid Client AMQP 1.0 (development ceased 0.32)
• jms-client  for AMQP protocols 0-8..0-10

To use the test suite, first configure the Java Broker to permit HTTP basic-authentication, then run the following command:

mvn -f joramtests/pom.xml integration-test -Djoramtests=<jms client identifier>

where <jms client identifier> is one of: qpid-jms-client, qpid-amqp-1-0-client-jms, jms-client-0-9, jms-client-0-10.

The Maven failsafe plugin will run the tests.  Unit output is produced in joram-tests/target/failsafe-reports and the log from the client is written to joramtests/target/joramtest.log.

To run a particular test use the failsafe plugin property -Dit.test:

mvn -f joramtests/pom.xml integration-test -Djoramtests=qpid-amqp-1-0-client-jms  -Dit.test=ConnectionTest

JMS TCK

The configuration for the JMS TCK is integrated into the Maven build but the profile is disabled by default.  The JMS TCK itself is proprietary and must be provided by the user.   The Java Broker must be running and HTTP management available. The test suite will automatically set-up/teardown the JMS objects required by the TCK.

• qpid-jms-client - Qpid Client AMQP 1.0
• jms-client  for AMQP protocols 0-8..0-10

To use the test suite, first unpack the JMS TCK into a directory, then invoke in the following way:

mvn post-integration-test -Dtck=qpid-jms-client -f tck/pom.xml -Dtck.directory=/path/to/jmstck/

To run an individual test, use the tck.test system property.

mvn post-integration-test -Dtck=qpid-jms-client -f tck/pom.xml -Dtck.directory=/path/to/jmstck/ -Dtck.test=com/sun/ts/tests/jms/ee/all/sessiontests/SessionTests.java

JMS 2.0 TCK can be run against Java Broker only with qpid-jms-client (for AMQP 1.0)  by specifying profile jms20-tck and location of directory containing expanded TCK. For example,

mvn post-integration-test -f tck/pom.xml -Pjms20-tck -Dtck.directory=/home/alex/tck/jmstck20 -Dqpid-jms-client-version=0.20.0

Performance Tests

The Performance test suite is integrated into Maven.  It is bound to the integration-test phase and it is activated by the  perftest system property.  The Java Broker must be running and HTTP management available. The test suite will automatically set-up/teardown the JMS objects required for the performance tests. 

The following clients are supported:

• qpid-jms-client - Qpid Client AMQP 1.0
• jms-client  for AMQP protocols 0-8..0-10

To invoke:

mvn  -f perftests/pom.xml integration-test -Dperftests=jms-client-0-9

Most things can be overridden from system properties.  Take a look in the first few lines of the POM.

Python Tests

The Python Test suite runs against the Java Broker too but is not currently integrated into Maven. To run the 0-8..0-10 test suites use the following steps.  It assumes that qpid-python and qpid-cpp are checked out.

1. Configure the Java Broker to allow so that the authentication provider permits plain connections. 

   curl --user admin:admin -d '{"secureOnlyMechanisms": []}' http://localhost:8080/api/latest/authenticationprovider/passwordFile

2. Install the Python packages to a suitable location.

   LOCALROOT=~/myroot
   (cd qpid-cpp/management/python && python setup.py install --root ${LOCALROOT})
   (cd qpid-python && python setup.py install --root ${LOCALROOT})
   export PYTHONPATH=${LOCALROOT}/lib/python2.7/site-packages

3. Run the tests will the following command:

   QPID_JAVA=/path/to/my/qpid-java
   cd qpid-python
   ./qpid-python-test  -b amqp://guest/guest@localhost:5672 -I${QPID_JAVA}/test-profiles/python_tests/Java010PythonExcludes -I${QPID_JAVA}/test-profiles/python_tests/JavaPre010PythonExcludes -m qpid_tests.broker_0_10 -m qpid_tests.broker_0_9 -m qpid_tests.broker_0_8 -m qmf.console [<fully qualified test name>]

Todo.  Describe the running of the AMQP 1.0 test suite using the swigged binding/proton-c.  See the https://builds.apache.org/view/M-R/view/Qpid/job/Qpid-Python-Java-Test/.

IDE integration

Nowadays, most of the team chose IntelliJ.

IntelliJ 

To setup the project, simply import the POM that resides at the top level.

Configuring the Annotation Processor

The build uses Java Annotation Processors to automatically generate code for things such as factories.  Intellij's annotation processor defaults don't play nicely with Maven.  A symptom of this is missing implementation classes when you try and start the Broker.

Go into "Preferences" -> "Annotation Processors"

• Ensure that the default profile includes all modules.
• Ensure that Enable Annotation Processing is ticked.
• Ensure that the Production Source Directory and Test Source Directory match that used by Maven. Choose Module Content Root and use the following paths.
  • target/generated-sources/annotations
  • target/generated-test-sources/test-annotations
• The option Obtain processors from project classpath does not seem to work.  As a workaround, you may use Processor Path specify the path to the codegen's JAR
  • /path/to/home/.m2/repository/org/apache/qpid/qpid-broker-codegen/6.2.0-SNAPSHOT/qpid-broker-codegen-6.2.0-SNAPSHOT.jar

This workaround does mean that you need to remember to mvn install each time the codegen project is changed, and update the version number each time the version number bumps.

Running the Broker within Intellij

TODO expand on this.

You need to

• specify QPID_WORK and QPID_HOME in the "VM options"
• set the class path to "qpid-broker"
• set the working directory to the root source folder
• add dojotoolkit and bdb to the "qpid-broker" module dependencies

Running System Tests within Intellij

Running system tests from within IntelliJ requires a bit of fiddeling. You first create a template configuration which you then need to adapt every time you want to run a different systest. This means this method does not support running the entire test suite.

1. Add a new Configuration
   1. "Run" --> "Edit Configurations..."
   2. Press the plus sign at the top left to add a new configuration and select "JUnit"
   3. Change the name to "Systest"
   4. Add these to the "VM options"
      1. -Dprofile.virtualhostnode.context.blueprint='{"type":"ProvidedStore","globalAddressDomains":"${dollar.sign}{qpid.gloabalAddressDomains}"}'
      2. -DQPID_HOME=<your Qpid home path>
      3. -DQPID_WORK=<your Qpid work path>
      4. -Dqpid.globalAddressDomains=[]
   5. Change the "Working Directory" to point to your source root folder (i.e., the folder containing the systests folder)
   6. Set "Use classpath of mod..." to "qpid-systests"
2. When you want to actually run a specific test, copy the fully qualified class name of the test into the "Class" field of this configuration before executing it.