Chapter 2. WS-Notification Tutorial

2.1. Install and Configure the Notification Broker

Overview

This section of the tutorial describes how to install and configure the notification broker as a Web service in the JBoss A-MQ standalone container. For convenient OSGi deployment, the notification broker is packaged as an Apache Karaf feature.

Prerequisites

This tutorial assumes that you are starting from a plain standalone container, in the initial configuration you find it in after installing JBoss A-MQ (and, in particular, that the container is not configured as part of a Fuse fabric).

Steps to install the notification broker

To install and configure the notification broker in the JBoss A-MQ container, perform the following steps:
  1. Make sure you have already configured some user accounts in the etc/users.properties file. If necessary, create a user account by adding lines in the following format: 
    Username=Password[,Role1][,Role2]...
    For example, this tutorial assumes that the following admin user account is defined (which has privileges defined by the admin role): 
    admin=admin,admin
  2. Create the notification broker configuration file, InstallDir/etc/org.apache.cxf.wsn.cfg, and use a text editor to add the following property settings: 
    cxf.wsn.activemq=vm://amq?create=false&waitForStart=10000
cxf.wsn.activemq.username=admin
cxf.wsn.activemq.password=admin
    The following aspects of the notification broker are configured in this file:
    • Connection to the ActiveMQ broker—the vm://amq URL connects through the Java Virtual Machine to access the broker named amq (where the broker's name is defined by the broker-name setting in the etc/org.fusesource.mq.fabric.server-default.cfg file). The following options are specified on this URL:
      create
      By setting create=false, you can ensure that the notification broker does not try to create its own (embedded) instance of a broker, but always tries to connect to the existing broker instance named amq.
      waitForStart
      To compensate for any delays that might occur during the container's start-up sequence, this endpoint defines a grace period, during which it waits for the broker to start.
    • Credentials for the connection—because authentication is enabled by default in the broker, you must provide credentials (username and password) for connecting to the broker. The credentials must refer to one of the user accounts defined in etc/users.properties.
  3. Start up the JBoss A-MQ container, by entering the following command from the InstallDir/bin directory: 
    ./amq
  4. Install and start up the notification broker using the features:install console command, as follows: 
    JBossA-MQ:karaf@root> features:install cxf-wsn
  5. Check that broker has started up by navigating to the following URL in your Web browser (querying the WSDL contract from the Web service endpoint): 
    http://localhost:8182/wsn/NotificationBroker?wsdl
    Note
    Your browser should display the NotificationBroker WSDL contract in response to this URL, but this does not work in all browsers. For example, the Safari browser just displays a blank page.

Troubleshooting

If you are not sure whether the notification broker is running properly, you can get some diagnostic information using the following commands:
osgi:list
If you run osgi:list at the console prompt, you should see some output like the following: 
JBossA-MQ:karaf@root> osgi:list
...
[ 149] [Active     ] [Created     ] [   40] Apache CXF API (2.6.0.redhat-60024)
[ 150] [Active     ] [Created     ] [   40] Apache CXF Runtime Core (2.6.0.redhat-60024)
[ 151] [Active     ] [            ] [   40] Apache CXF Runtime Management (2.6.0.redhat-60024)
[ 152] [Active     ] [Created     ] [   40] Apache CXF Karaf Commands (2.6.0.redhat-60024)
[ 153] [Active     ] [            ] [   30] Apache Neethi (3.0.2)
[ 154] [Active     ] [Created     ] [   40] Apache CXF Runtime WS Policy (2.6.0.redhat-60024)
[ 155] [Active     ] [            ] [   40] Apache CXF Runtime XML Binding (2.6.0.redhat-60024)
[ 156] [Active     ] [Created     ] [   40] Apache CXF Runtime SOAP Binding (2.6.0.redhat-60024)
[ 157] [Active     ] [Created     ] [   40] Apache CXF Runtime WS Addressing (2.6.0.redhat-60024)
[ 158] [Active     ] [            ] [   40] Apache CXF Runtime JAXB DataBinding (2.6.0.redhat-60024)
[ 159] [Active     ] [Created     ] [   40] Apache CXF Runtime HTTP Transport (2.6.0.redhat-60024)
[ 160] [Active     ] [Created     ] [   40] Apache CXF Runtime Simple Frontend (2.6.0.redhat-60024)
[ 161] [Active     ] [Created     ] [   40] Apache CXF Runtime JAX-WS Frontend (2.6.0.redhat-60024)
[ 162] [Active     ] [            ] [   60] Apache CXF WSN API (2.6.0.redhat-60024)
[ 163] [Active     ] [Created     ] [   40] Apache CXF Runtime HTTP Jetty Transport (2.6.0.redhat-60024)
[ 166] [Active     ] [Created     ] [   60] Apache CXF WSN Core (2.6.0.redhat-60024)
In particular, the Apache CXF WSN Core bundle (which deploys the notification broker server) must have the status Active and Created.
log:display
Run the log:display command at the console prompt to search the container log for errors and warnings.

org.apache.cxf.wsn.cfg settings

You can set the following properties in the etc/org.apache.cxf.wsn.cfg configuration file:
cxf.wsn.activemq
Specifies the URI for connecting to the ActiveMQ broker (must be an ActiveMQ client URL). Default is vm:localhost.
cxf.wsn.activemq.username
Specifies the username credentials for logging on to the ActiveMQ broker. Default is user.
cxf.wsn.activemq.password
Specifies the password credentials for logging on to the ActiveMQ broker. Default is password.
cxf.wsn.rootUrl
Specifies the host and IP port of the notification broker's Web service endpoints. Default is http://0.0.0.0:8182.
cxf.wsn.context
Defines the servlet context for notification broker's Web service endpoints. Default is /wsn.
By default, the notification broker constructs its NotificationBroker endpoint address and its CreatePullPoint endpoint address as follows: 
${cxf.wsn.rootUrl}${cxf.wsn.context}/NotificationBroker
${cxf.wsn.rootUrl}${cxf.wsn.context}/CreatePullPoint

Advanced configuration

Because the ActiveMQ broker provides the core functionality of the notification broker, most of the configuration options are available in the etc/activemq.xml file. For example, through the settings in this file you can configure persistent storage and you can optimize the broker for optimum performance.
For more details, see Managing and Monitoring a Broker and Configuring Broker Persistence.