Introduction
What is an Enterprise Service Bus?Why PHP?Why Blackbird?Why Not Blackbird?
Getting Started
PrerequisitesDownloading and Installing BlackbirdConfiguring an ESB InstanceRunning and Managing
Developing With Blackbird
Basic TheoryCallback FunctionsProtocol HandlersUsing Sandpiper
Use Cases
Stock Trading Grey BoxWeb Service IntegrationSales Order Integration

ActiveMQ

Before you begin, you must have a running ActivMQ service with the STOMP protocol configured. This is a relatively straightforward process. We don't have room to repeat Apache's ActiveMQ documentation here, but the general idea is:

1. Go to http://activemq.apache.org/download.html and obtain the release you'd like to run. Blackbird was tested on version 4.1.1, but it should run on any version that properly implements the STOMP protocol (anything recent).
2. Untar the distribution package to a directory you'd like to run it from.
3. Edit conf/activemq.xml and find the line that reads
   <transportConnector name="stomp" uri="stomp://localhost:61613"/>
4. Make sure the line is not commented out, and that you're happy with the port number STOMP will use. Write it down - you'll need it to configure Blackbird.
5. Start ActiveMQ by running bin/activemq. Read the log output, and fix any problems before proceeding.

Multiple Blackbirds (and Apache ServiceMix) instances can share one ActiveMQ instance. Just bear in mind that ActiveMQ doesn't currently implement much in the way of authentication or access control. If you want more isolation, you can set up more ActiveMQ instances - just be sure to keep track of your STOMP ports!

Nest

Nest is Blackbird's management server. You don't have to use it, but we strongly recommend it. It currently offers the ability to monitor and manage a Blackbird instance, and we'll be adding much more functionality to it down the road.

When Blackbird starts, it expects to connect to a Nest, send the Nest metrics data, and receive control commands. A management application (Motherbird) can connect to a Nest server and view the Blackbirds that are running, control them, and receive metrics from them. Like ActiveMQ, Nest can run on a different machine from Blackbird itself, so it can be used to manage a cluster of Blackbird nodes.

You can run Nest right from the Blackbird installation directory. If you want more than one instance, or you just want to run it from somewhere else, copy the Nest subdirectory's contents to it:

$ mkdir /opt/nest1
$ cp /opt/blackbird/blackbird/Nest/* /opt/nest1

Then edit /opt/nest1/nest.conf. There are currently only two options, the IP address (or hostname) to bind to, and the port to listen on.

Next, make a user.perms permissions file:

$ cp /opt/nest1/demo.perms /opt/nest1/user.perms 

and edit the file. There are comments in the file that will walk you through how to set up user permissions. Be sure you write down the Blackbird instance name (which must be unique, and one word), username, and password you'll be using.

Sandpiper (Optional)

Sandpiper is a SOAP service helper. It makes it much easier to set up a SOAP interface into the bus - you create a WSDL file defining the endpoint, a class that implements the appropriate callback, and a configuration file for the class, and Sandpiper handles the rest. To install it, use the contents of docs/apache2/sandpiper.site to set up a site entry in your Apache server. It should reference the /opt/blackbird/lib/Sandpiper subdirectory, or a copy of it.

For more information on Sandpiper, please see the appropriate documentation section.

Blackbird

You can run Blackbird directly from its installation directory. If you'd like to run more than one instance, make copies of this directory to where you'd like to run it from:

$ mkdir /opt/blackbirds/BBname
$ cp -aR /opt/blackbird/blackbird/Blackbird/* /opt/blackbirds/BBname

Either way, edit the configuration/blackbird.conf file from where you'll run Blackbird. Set the ID option to the instance name you provided Nest. Also, make sure the nest connection options are correct to connect to your Nest instance. You can leave the rest of the options alone for now. (If you're wondering where the ActiveMQ options are, because Blackbird supports 0 or more MQ connections, they're specified in the module configuration files when modules are loaded.)

Other configuration info can be found in the Running and Managing Page.

Logging Considerations

Blackbird has its own internal logger, which can be configured by editing the entry point element of any management process (Environment, Blackbird, Sandpiper). However, by default, Blackbird will attempt to create logs within the /var/log/blackbird, /var/log/nest, and /var/log/sandpiper directories (naming each log file as the date which it was populated). If you wish to use these default directories, you must create them and allow php to write to them.