This chapter gives a brief description on how to use the \class{AsyncJMSWriter} and \class{JMSReader} %
classes. The directory \dir{\JMSBookstoreApplicationDirDistro/} contains the %
sources, ant scripts etc.\ used in this example. It is based on the Bookstore %
application with manual instrumentation presented in Chapter~\ref{chap:example}. %

The following sections provide step-by-step instructions for the %
JMS server implementations ActiveMQ (Section~\ref{example:jms:activemq}), %
HornetQ~(\ref{example:jms:hornetq}), and OpenJMS~(\ref{example:jms:openjms}).
The general procedure for each example is the following:

\medskip

\begin{compactenum}
 \item Download and prepare the respective JMS server implementation
 \item Copy required libraries to the example directory
 \item Start the JMS server
 \item Start the analysis instance which receives records via JMS
 \item Start the monitoring instance which sends records via JMS
\end{compactenum}

\

\WARNBOX{\quad\\Due to a bug in some JMS servers, avoid paths including white spaces.}

\section{ActiveMQ}\label{example:jms:activemq}

\subsection{Download and Prepare ActiveMQ}

Download an ActiveMQ archive from \url{http://activemq.apache.org/download.html}
and decompress it to the base directory of the example. Note, that there are two different %
distributions, one for Unix/Linux/Cygwin and another one for Windows. 

Under \UnixLikeSystems{}, you'll need to set the executable-bit of the start script:

\setBashListing
\begin{lstlisting}[caption=]
 #\lstshellprompt{}# chmod +x bin/activemq
\end{lstlisting}

\noindent Also under \UnixLikeSystems{}, make sure that the file \file{bin/activemq} %
includes UNIX line endings (e.g., using your favorite editor or the \textit{dos2unix} tool).

\subsection{Copy ActiveMQ Libraries}

Copy the following files from the ActiveMQ release to the %
\dir{lib/} directory of this example:

\medskip

\enlargethispage{0.5cm}

\begin{compactenum}
\item \file{activemq-all-<version>.jar} (from ActiveMQ's base directory)
\item \file{slf4j-log4j<version>.jar} (from ActiveMQ's \dir{lib/optional} directory)
\item \file{log4j-<version>.jar} (from ActiveMQ's \dir{lib/optional} directory)
\end{compactenum}

\subsection{Kieker Monitoring Configuration for ActiveMQ}

The file \file{\JMSBookstoreApplicationDirDistro/META-INF/kieker.monitoring.\-pro\-perties-activeMQ} %
is already configured to use the \class{AsyncJMSWriter} via ActiveMQ. The important properties are %
the definition of the provider URL and the context factory:

\setPropertiesListing
\lstinputlisting[firstline=12,lastline=12,caption=Excerpt from \file{kieker.monitoring.properties-activemq} configuring the provider URL of the JMS writer via ActiveMQ]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-activemq}

\setPropertiesListing
\lstinputlisting[firstline=21,lastline=21,caption=Excerpt from \file{kieker.monitoring.properties-activemq} configuring the context factory of the JMS writer via ActiveMQ]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-activemq}

\subsection{Running the Example}

% \paragraph*{Execution}%
 The execution of the example is performed by the following three steps:
\begin{enumerate}
\item Start the JMS server (you may have to set your \class{JAVA\_HOME} variable first):

\setBashListing
\begin{lstlisting}[caption=Start of the JMS server under UNIX-like systems]
#\lstshellprompt{}# bin/activemq start
\end{lstlisting}
\begin{lstlisting}[caption=Start of the JMS server under Windows]
#\lstshellprompt{}# bin\#activemq start
\end{lstlisting}
\item Start the analysis part (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-analysis-activemq
\end{lstlisting}
\item Start the instrumented Bookstore (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-monitoring-activemq
\end{lstlisting}
\end{enumerate}


\section{HornetQ}\label{example:jms:hornetq}

\subsection{Download and Prepare HornetQ}

Download a HornetQ archive from \url{http://www.jboss.org/hornetq/downloads.html} %
and decompress it to the root directory of the example. 

\noindent You need to create a queue in the HornetQ configuration file %
\file{config/stand-alone/non-clustered/hornetq-jms.xml}, as shown in Listing~\ref{lst:hornetq:config:queue}.

\setXMLListing
\begin{lstlisting}[caption=Queue definition to be added to the HornetQ configuration file,label=lst:hornetq:config:queue,numbers=none]
  <queue name="queue1">
      <entry name="/queue/queue1"/>
  </queue>
\end{lstlisting}

\subsection{Copy HornetQ Libraries}

Copy the following files from the HornetQ \dir{lib/} folder to the %
\dir{lib/} directory of this example:

\medskip

\begin{compactenum}
\item \file{hornetq-jms-client.jar}
\item \file{hornetq-commons.jar} (if available)
\item \file{hornetq-core-client.jar}
\item \file{jboss-jms-api.jar}
\item \file{jnp-client.jar}
\item \file{netty.jar}
\end{compactenum}

\subsection{Kieker Monitoring Configuration for HornetQ}

The file \file{\JMSBookstoreApplicationDirDistro/META-INF/kieker.monitoring.\-pro\-perties-hornetq} %
is already configured to use the \class{AsyncJMSWriter} via HornetQ. The important properties are %
the definition of the provider URL, the context factory, and the queue:

\setPropertiesListing
\lstinputlisting[firstline=12,lastline=12,caption=Excerpt from \file{kieker.monitoring.properties-hornetq} configuring the provider URL of the JMS writer via HornetQ]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-hornetq}

\setPropertiesListing
\lstinputlisting[firstline=21,lastline=21,caption=Excerpt from \file{kieker.monitoring.properties-hornetq} configuring the context factory of the JMS writer via HornetQ]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-hornetq}

\subsection{Running the Example}

% \paragraph*{Execution}%
 The execution of the example is performed by the following three steps:
\begin{enumerate}
\item Start the JMS server:

\setBashListing
\begin{lstlisting}[caption=Start of the JMS server under UNIX-like systems]
#\lstshellprompt{}# ./run.sh
\end{lstlisting}
\begin{lstlisting}[caption=Start of the JMS server under Windows]
#\lstshellprompt{}# run.bat
\end{lstlisting}

Note that the script must be called from within HornetQ's \dir{bin/} directory.

\item Start the analysis part (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-analysis-hornetq
\end{lstlisting}
\item Start the instrumented Bookstore (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-monitoring-hornetq
\end{lstlisting}
\end{enumerate}

\WARNBOX{\quad\\Note that recent HornetQ versions require Java > 6.}

\section{OpenJMS}\label{example:jms:openjms}

\subsection{Download and Prepare OpenJMS}

Download an OpenJMS install archive from \url{http://openjms.sourceforge.net} %
and decompress it to the root directory of the example. Under UNIX-like systems, make sure that the executable-bit of all scripts within the \dir{bin/} directory are set.

\subsection{Copy OpenJMS Libraries}

Copy the following files from the OpenJMS \dir{lib/} folder to the %
\dir{lib/} directory of this example:

\medskip

\begin{compactenum}
\item \file{openjms-<version>.jar}
\item \file{openjms-common-<version>.jar}
\item \file{openjms-net-<version>.jar}
\item \file{jms-<version>.jar}
\item \file{concurrent-<version>.jar}
\item \file{spice-jndikit-<version>.jar}
\end{compactenum}

\subsection{Kieker Monitoring Configuration for OpenJMS}

The file \file{\JMSBookstoreApplicationDirDistro/META-INF/kieker.monitoring.\-pro\-perties-openjms} %
is already configured to use the \class{AsyncJMSWriter} via OpenJMS. The important properties are %
the definition of the provider URL and the context factory:

\setPropertiesListing
\lstinputlisting[firstline=12,lastline=12,caption=Excerpt from \file{kieker.monitoring.properties-openjms} configuring the provider URL of the JMS writer via OpenJMS]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-openjms}

\setPropertiesListing
\lstinputlisting[firstline=21,lastline=21,caption=Excerpt from \file{kieker.monitoring.properties-openjms} configuring the context factory of the JMS writer via OpenJMS]{\JMSBookstoreApplicationDir/META-INF/kieker.monitoring.properties-openjms}

\subsection{Running the Example}

% \paragraph*{Execution}%
 The execution of the example is performed by the following three steps:
\begin{enumerate}
\item Start the JMS server (you may have to set your \class{JAVA\_HOME} and \class{OPENJMS\_HOME} variables first):

\setBashListing
\begin{lstlisting}[caption=Start of the JMS server under UNIX-like systems]
#\lstshellprompt{}# openjms-<version>/bin/startup.sh
\end{lstlisting}
\begin{lstlisting}[caption=Start of the JMS server under Windows]
#\lstshellprompt{}# openjms-<version>\bin\startup.bat
\end{lstlisting}
\item Start the analysis part (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-analysis-openjms
\end{lstlisting}
\item Start the instrumented Bookstore (in a new terminal):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# ant run-monitoring-openjms
\end{lstlisting}
\end{enumerate}
