Download Introducing the Java Wrapper

Chapter 4. Using the Java Wrapper
The Java wrapper provides an alternative way to start the broker, which you can optionally use in place of the
standard Fuse Message Broker scripts.
Introducing the Java Wrapper ...................................................................................................
Configuring the Wrapper ..........................................................................................................
Running in the Foreground .......................................................................................................
Running as a Windows Service .................................................................................................
Running as a Daemon Process ..................................................................................................
Fuse Message Broker Getting Started Version 5.5
58
60
63
65
66
57
Chapter 4. Using the Java Wrapper
Introducing the Java Wrapper
Overview
The Java wrapper is an alternative approach to starting a broker instance,
1
which is based on the Java service wrapper from Tanuki Software Ltd. The
Java service wrapper provides a general solution to the problem of launching
a Java application. Although the Java platform itself is operating system
independent, it is typically necessary to provide a large number of (potentially
O/S-specific) JVM and application parameters when starting a Java application.
In addition, the Java platform on its own provides no support for deploying
an application either as a Windows service or as a UNIX daemon. These
difficulties are solved, in an O/S-independent way, by the Java service wrapper.
Features
The Java service wrapper offers the following features:
• O/S-independent wrapper utility for running Java applications.
• O/S-independent configuration of the wrapper utility.
• Support for installing broker as a Windows service.
• Support for running broker as a UNIX daemon.
• Control logging by redirecting stdout and stderr channels.
• Control the service wrapper remotely through JMX (for details, see
2
Controlling the Service Wrapper using JMX ).
Provided scripts
The following scripts are provided for launching a broker using the Java service
wrapper:
Windows
The following .bat scripts are provided on Windows:
activemq.bat
Start the broker in the foreground.
1
2
http://www.tanukisoftware.com/en/wrapper.php
http://wrapper.tanukisoftware.com/doc/english/jmx.html
58
Fuse Message Broker Getting Started Version 5.5
Introducing the Java Wrapper
InstallService.bat
Install the broker as a Windows service.
UninstallService.bat
Uninstall the broker from the service registry.
*NIX
The activemq shell script for *NIX O/Ss provides typical daemon
capabilities.
The wrapper executable
3
4
Ultimately, the scripts call the wrapper executable (wrapper.exe on
Windows) to launch an application (the broker, in this case). You could use
the wrapper executable directly, but in practice the provided scripts are more
convenient. For more details about the wrapper executable, see Using
3
4
wrapper.exe Directly for Windows and Using Wrapper Directly for *NIX.
http://wrapper.tanukisoftware.com/doc/english/launch-win.html#exe
http://wrapper.tanukisoftware.com/doc/english/launch-nix.html#exe
Fuse Message Broker Getting Started Version 5.5
59
Chapter 4. Using the Java Wrapper
Configuring the Wrapper
Overview
The wrapper is configured by the O/S-independent wrapper.conf file, which
is located under the ActiveMQInstallDir/bin/OS/ directory. O/S-specific
scripts (for Windows and *NIX respectively) are then used to launch the
application, based on the settings in the wrapper.conf file.
Reference
For a complete description of all the properties you can set in the
5
wrapper.conf configuration file, see Configuration Property Overview at
the Tanuki Web site.
Setting ACTIVEMQ_HOME and
ACTIVEMQ_BASE
It is likely that you will need to customize the values of the ACTIVEMQ_HOME
and ACTIVEMQ_BASE properties in the wrapper.conf file. The default values
are set as follows in wrapper.conf:
set.default.ACTIVEMQ_HOME=../..
set.default.ACTIVEMQ_BASE=../..
These properties have the following meaning:
ACTIVEMQ_HOME
The location of the Fuse Message Broker install directory (that is, binaries
and libraries are located relative to this directory).
ACTIVEMQ_BASE
The directory containing data specific to the current broker instance (that
is, the /data and /conf directories are located relative to this directory).
Note
When specifying file and directory paths in the wrapper.conf file,
the forward slash, /, is also used on Windows operating systems.
Passing additional parameters to
the JVM
5
If you want to pass additional parameters to the JVM (that is, pass parameters
directly to the java command), you can do so by setting wrapper properties
http://wrapper.tanukisoftware.com/doc/english/properties.html
60
Fuse Message Broker Getting Started Version 5.5
Configuring the Wrapper
of the form, wrapper.java.additional.<n>, where <n> is a sequence
number that must be distinct for each parameter.
Setting Java system properties
In particular, one of the most useful things you can do by passing additional
parameteres to the JVM is to set Java system properties. The syntax for setting
a Java system property is as follows:
wrapper.java.additional.<n>=-DPropName=PropValue
For example, the wrapper.conf file sets the following system properties by
default:
# Java Additional Parameters
# note that n is the parameter number starting from 1.
wrapper.java.additional.1=-Dactivemq.home="%ACTIVEMQ_HOME%"
wrapper.java.additional.2=-Dactivemq.base="%ACTIVEMQ_BASE%"
wrapper.java.additional.3=-Djavax.net.ssl.keyStorePassword=password
wrapper.java.additional.4=-Djavax.net.ssl.trustStorePassword=password
wrapper.java.additional.5=-Djavax.net.ssl.keyStore="%ACTIVEMQ_BASE%/conf/broker.ks"
wrapper.java.additional.6=-Djavax.net.ssl.trustStore="%ACTIVEMQ_BASE%/conf/broker.ts"
wrapper.java.additional.7=-Dcom.sun.management.jmxremote
wrapper.java.additional.8=-Dorg.apache.activemq.UseDedicatedTaskRunner=true
wrapper.java.additional.9=-Djava.util.logging.config.file=logging.properties
Setting application parameters
You can specify application parameters by setting wrapper properties of the
form, wrapper.app.parameter.<n>, where <n> is a sequence number that
must be distinct for each parameter. The following application parameters
are set by default in wrapper.conf:
# Application parameters. Add parameters as needed starting
from 1
wrapper.app.parameter.1=org.apache.activemq.console.Main
wrapper.app.parameter.2=start
The first parameter is the name of the Java class executed by the wrapper.
Subsequent parameters (numbered 2) are passed to the application.
Adding classpath entries
You can add classpath entries by setting wrapper properties of the form,
wrapper.java.classpath.<n>, where <n> is a sequence number that must
be distinct for each classpath entry.
For example, the following classpath entries are set by default in
wrapper.conf:
Fuse Message Broker Getting Started Version 5.5
61
Chapter 4. Using the Java Wrapper
# Java Classpath (include wrapper.jar) Add class path elements
as
# needed starting from 1
wrapper.java.classpath.1=%ACTIVEMQ_HOME%/bin/wrapper.jar
wrapper.java.classpath.2=%ACTIVEMQ_HOME%/bin/run.jar
Enabling wrapper debugging
To enable wrapper debugging, uncomment the following line in the
wrapper.conf file:
# wrapper.debug=TRUE
When this property is set to TRUE, logging information is appended to the
wrapper.log file (or whatever file location is specified by the
wrapper.logfile property).
62
Fuse Message Broker Getting Started Version 5.5
Running in the Foreground
Running in the Foreground
Starting the broker on Windows
After customizing the wrapper.conf configuration file as described in
"Configuring the Wrapper" on page 60, change directory to the
ActiveMQInstallDir\bin\win32 directory, and launch the broker using the
activemq.bat script, as follows:
C:\Programs\apache-activemq5.5.0-fuse-00-07\bin\win32>activemq
wrapper | --> Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1
| Wrapper (Version 3.2.3) http://wrapper.tanukisoft
ware.org
...
By default, the working directory of the application is the current directory
(ActiveMQInstallDir\bin\win32). The data and configuration files are
located relative to ACTIVEMQ_BASE, which is ../.. by default. Hence, the
default wrapper configuration uses the ActiveMQInstallDir\data directory
and the ActiveMQInstallDir\config configuration directory.
Starting the broker on *NIX
After customizing the wrapper.conf configuration file as described in
"Configuring the Wrapper" on page 60, change directory to the relevant UNIX
O/S directory under ActiveMQInstallDir/bin/ (either /bin/macos,
/bin/linux-x86-32, /bin/linux-x86-64, or /bin/solaris) and launch
the broker by entering the command, activemq console.
For example, to launch the broker using the service wrapper on Linux 32-bit:
/usr/lib/apache-activemq5.5.0-fuse-00-07/bin/linux-x8632>activemq console
Running ActiveMQ Broker...
wrapper | --gt Wrapper Started as Console
wrapper | Launching a JVM...
jvm 1
| Wrapper (Version 3.2.3) http://wrapper.tanukisoft
ware.org
...
Stopping the broker
To stop the broker, type Ctrl-C in the console window. This works on both
Windows and *NIX operating systems.
For example, on Windows, the wrapper logs the following messages as it
shuts down:
Fuse Message Broker Getting Started Version 5.5
63
Chapter 4. Using the Java Wrapper
wrapper | CTRL-C trapped. Shutting down.
jvm 1
| INFO | ActiveMQ Message Broker (localhost, ID:jdoe2210-1306940424328-0:1) is shutting down
jvm 1
| INFO | ActiveMQ Message Broker (localhost, ID:jdoe2210-1306940424328-0:1) is shutting down
...
64
Fuse Message Broker Getting Started Version 5.5
Running as a Windows Service
Running as a Windows Service
Overview
On Windows, Fuse Message Broker provides the
bin\win32\InstallService.bat and bin\win32\UninstallService.bat
scripts to install and uninstall the broker as a Windows service.
Installing the broker as a service
After customizing the wrapper.conf configuration file as described in
"Configuring the Wrapper" on page 60, change directory to the
ActiveMQInstallDir\bin\win32 directory, and install the broker as a
Windows service, using the InstallService.bat script, as follows:
C:\Programs\apache-activemq5.5.0-fuse-00-07\bin\win32>Install
Service
wrapper | ActiveMQ installed.
Stopping and starting the broker
You can start and stop the installed ActiveMQ service using the Windows
net start and net stop tools at the command line.
For example, you can start the installed ActiveMQ service, as follows:
> net start ActiveMQ
The ActiveMQ service is starting.........
The ActiveMQ service was started successfully.
You can stop the installed ActiveMQ service, as follows:
> net stop ActiveMQ
The ActiveMQ service is stopping...
The ActiveMQ service was stopped successfully.
Uninstalling the broker
To remove the broker from the Windows service registry, run the
UninstallService.bat script, as follows:
C:\Programs\apache-activemq5.5.0-fuse-00-07\bin\win32>Unin
stallService
wrapper | ActiveMQ removed.
Fuse Message Broker Getting Started Version 5.5
65
Chapter 4. Using the Java Wrapper
Running as a Daemon Process
Overview
On UNIX and LINUX (*NIX) operating systems, you can start the broker as a
daemon process using the bin/OS/activemq shell script.
activemq script
The activemq script in the ActiveMQInstallDir/bin/UnixOs has the following
command-line syntax:
activemq ( console | start | stop | restart | status | dump
)
Where the command options work as follows:
console
Start the broker in the foreground.
start
Start the broker in the background, by forking a new daemon process.
stop
Stop the daemon process.
restart
Stop and then start the daemon process.
status
Checks whether the daemon is currently running or not.
dump
Sends a kill -3 signal to the daemon process, which causes the JVM
to do a full thread dump.
Starting the broker as a daemon
process
66
After customizing the wrapper.conf configuration file as described in
"Configuring the Wrapper" on page 60, change directory to the relevant UNIX
O/S directory under ActiveMQInstallDir/bin/ (either /bin/macos,
/bin/linux-x86-32, /bin/linux-x86-64, or /bin/solaris) and launch
the broker daemon by entering the command, activemq start, as follows:
Fuse Message Broker Getting Started Version 5.5
Running as a Daemon Process
$ activemq start
Running ActiveMQ Broker...
Stopping the broker daemon
To stop the broker daemon, enter the command activemq stop, as follows:
$ activemq stop
Stopping ActiveMQ Broker...
Stopped ActiveMQ Broker.
Fuse Message Broker Getting Started Version 5.5
67
68
Fuse Message Broker Getting Started Version 5.5