Logging anti patterns

First of all let’s go throught logging anti patterns described years ago by Gojko Adzic. They are really good and shows how to avoid common problems:

• Single log file for all people
• Lack of hierarchy in log categories (that’s mine idea)
• Incomplete data in entries (covers also one information split to multiple entries)
• Different separators in single line
• Inconsistent log entry format (covers also inconsistent log entry format)
• Multi-line entries
• Populating log after the action

Let describe comon mistakes we can do with Camel and how these anti patterns can look in our case. My thoughts can be really close to Gojko, but I’ll try to show you where you can meet these anti patterns on Java ground.

Single log file

As usual log file can be used by different people for diagnostic – eg. database administrators are not interested in all java stuff we do. Message processing, filtering and so on. They want to see query, their parameters and execution time. Nothing else. System administrators are another group which are forced to read dozen of lines to find exception with message ‘Too many open files’. IOExceptions are definitely category important for these people more than surrounding. We can leverage existing features from logging framework to create advanced filters to route logs.

Lack of hierarchy in log categories

Many libraries use a single log category or only few to do logging. That’s completly wrong idea. Let take a look for Atomikos. By default all log are produced by ‘atomikos’ category. Even if you are interested in connection pooling tracing you are forced to see almost all events happened from begining of transaction to it’s end. In case of Apache Camel and middleware – consider:

• Usage of own categories, different than a framework which will reflect your mediation process logic, not technical details. Even if you are genius programmer you can be confused by log entries not connected with any process stage.
• Be sure that all events produced by your processors, classes and context or route go to same log hierarchy – eg. org.code_house.esb.sap.finance, instead of “processor”, “org.myjavapackage” and so on. Be consistent on that.
• Do not trust a thread name and do not use it as the category. Name of it can be changed by camel core change or component update.

Camel components have a proper packages and you can easily get rid of statements unnecessary for you.

Incomplete data in entries

That’s I think most common mistake. The best example is Hibernate and SQL parameters logging. To get all data related to SQL query exceution and parameter binding we all are forced to use two totally different categories which are not in same hierarchy. If you are happy with setting TRACE level for org.hibernate package you can skip this example.
If you have all parameters and SQL query put it together to log stream. Even if line will be insane long you will be sure that you see parameters for this SQL query, not two different.

Different separators in single line

I like to have a log with brackets, pipes and dots. This is so geeky. You look like guy who can see matrix and knows what is happening. Actually you do, but text processing tools are not so smart as we. Parsing is as complex as log pattern is. So don’t use too complex patterns in production and try to use singular separator. Some commercial tools require a special log format. Cook it for this tool in separate file or use different appender. Even if it is redundant. Keep main log clear and not affected by specific format which cuts 50% of diagnostic information or make it harder to read.

Multi-line entries

Just imagine that your SQL query have 5 lines. Not too much, isn’t? But what’s when you have a 200KB (or more) payload? Your log will grow quicker than disk size. Basically multi line entries can make parsing harder, but also makes log file longer and harder to read. If you need to keep messages don’t do that in log file. That’s not place for that. Reuse auditing features from ServiceMix NMR or archive ActiveMQ store. You can also build your own mechanism as well if these are not sufficient using asynchronous Wire Tap pattern.

Populating log after the action

Latest anti-pattern – remember that logs are produced by code should prelude a operation. Not other – otherwise log entry before exception will point to mediation which was fine or your will be not able to say what happened with given message. If you are against this point remember to notify people about your logging behavior. Most of them expect that log stream allows to see path before error occured (I received message with given ID), error (exception during message transofrmation) and recovery actions (message moved to dead letter).

Best practices of logging with Apache Camel

Apache Camel uses slf4j as logging library. It’s a generic facade to many different logging libraries. You don’t have to use it in your project directly, you still can use Log4j or commons-logging, but it’s always the better to have less dependencies and clean classpath. I will not complain about ideas behind slf4j here, just point to your nous and let you nod.

Name your elements

If you going to live with your middleware you should know what happens when. Especially that you will have difficulty to access production environment with your lovely IDE and debugger. That’s why at least camel context should have a name. From runtime management point of view it should always have a given name. If you have a JMX console to do some administrative operations than 182-camel-10 is confusing. Just see image on right side and try to say what the following processors do. Sure, you can do that by walking whole JMX tree.

Use a Mapper Diagnostic Context (MDC)

MDC is an bridge from your application to logging framework. You can set some application specific variables and then re-use them to create rich log format or distinct log files by application id (yeah, it seems like missing feature in Tomcat for me too). This feature is disabled by default for Camel but it might be easily turned on. Let’s have a look on MDC variables set by Apache Camel:

• breadcrumbId
• exchangeId
• messageId
• correlationId
• routeId
• camelContextId
• transactionKey

Each variable from this list can be used in combination with log format or appender. For example if you have all variables set correctly you can use this format:

log4j.appender.out.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %X{camelContextId} %X{bundle.version} | %X{routeId} %X{exchangeId} | %m%n

And you will get following line produced:

23:56:12,158 | INFO  | database-batch 2.8.0.fuse-01-06 | jms-inbound-hr | ID-Code-House-local-60526-1330335502920-25-33 | Received message

For me it’s still do not look like something easy to read, that’s why I introduce appender:

log4j.appender.integrationProcess=org.apache.log4j.sift.MDCSiftingAppender
log4j.appender.integrationProcess.key=camelContextId
log4j.appender.integrationProcess.default=unknown
log4j.appender.integrationProcess.appender=org.apache.log4j.RollingFileAppender
log4j.appender.integrationProcess.appender.layout=org.apache.log4j.PatternLayout
log4j.appender.integrationProcess.appender.layout.ConversionPattern=%d{ABSOLUTE} | %-5.5p | %X{routeId} %X{bundle.version} | %X{exchangeId} | %m%n
log4j.appender.integrationProcess.appender.file=${karaf.data}/log/mediation-$\\{camelContextId\\}.log
log4j.appender.integrationProcess.appender.append=true
log4j.appender.integrationProcess.appender.maxFileSize=1MB
log4j.appender.integrationProcess.appender.maxBackupIndex=10

log4j.category.com.mycompnany.camel_toys.hr=INFO, integrationProcess

By default, when the camelContextId is not set log entries will be appended to file data/log/mediation-unknown.log. But for these which have a context ID it will look much better (file mediation-database-batch.log):

00:38:42,386 | INFO  | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-67 | Received message with business key XYZ.
00:38:43,387 | INFO  | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-67 | Saving message in database
00:38:44,388 | INFO  | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-67 | Processing of message with business key XYZ complete.
00:38:44,389 | INFO  | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-68 | Received message with business key ZYX.
00:38:45,390 | INFO  | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-68 | Saving message in database
00:38:45,391 | ERROR | jms-inbound-hr 2.8.0.fuse-01-06 | ID-Code-House-local-51055-1330383822002-4-68 | Processing of message with business key ZYX failed.

As you see these log entries contains only a process specific informations and they are not influenced by technical details. A category is skipped because it is not relevant in this context (it still for developer logging but not here). Also you don’t have to extract a business key. You might use a breadcrumbId header or correlationId property.
Before you will start using MDC be aware that the property names might be changed because issue CAMEL-5047 Clean up MDC property names. This configuration was tested with Camel up to 2.9 release. The bundle.version property is set by pax-logging, not Camel and I treat it as a mediation process version. Log4j sift appender is a wrapper so it will work also with syslog or an database appender.

Embedded processors

Embedded processors are something common in java DSL. If you use them your category will contain a dollar sign (my.company.RouteBuilderExt$1). Then you should not implement too complex logic in it. If you need do something more than glue strings or set header and you wish to log that – then create a separate class and remember about log category hierarchy and do not use a RouteBuilder log category. Processor logic is deeper than the route builder’s and you do some specific task. Separate it. Keep same approach for AggreagatorStrategy and org.apache.camel.spi extensions.

package com.mycompnany.camel_toys.hr;
public class Route extends RouteBuilder {

    Log log = LogFactory.getLog(Route.class);

    @Override
    public void configure() throws Exception {
        from("")
            .onException(Exception.class)
                .process(new Processor() {
                    @Override
                    public void process(Exchange exchange) throws Exception {
                        org.apache.camel.Message out = exchange.getOut();
                        out.setHeader(org.apache.cxf.message.Message.RESPONSE_CODE, new Integer(500));
                        log.error("Unexpected exception", exchange.getException());
                    }
                }
            })
            .end()
            .to("")
    }
}

It’s better to have:

package com.mycompnany.camel_toys.hr; // or .processor if we have few or logic is complex
public class ExceptionProcessor implements Processor {
    // slf4j!
    private Log log = LoggerFactory.getLogger(ExceptionProcessor.class);
    @Override
    public void process(Exchange exchange) throws Exception {
        org.apache.camel.Message out = exchange.getOut();
        out.setHeader(org.apache.cxf.message.Message.RESPONSE_CODE, new Integer(500));
        log.error("Unexpected exception", exchange.getException());
    }
}

Usage of camel-log component

Most of use this component in more or less proper way. For example:

onException(Exception.class)
    .log("Unexpected exception ${exception}")
.end()

By default your logging category will be set to route id (eg route4, route5 etc) which will obviously not help in detecting the issues. Also log level is not present so it’s set by default to INFO. A proper usage is:

onException(Exception.class)
    // see, I have here a same category as route builder because it's on same level
    .log(LoggingLevel.ERROR, "com.mycompnany.camel_toys.hr", "Unexpected exception ${exception}")
.end()

Quick summary

It’s too late to continue this blog entry, but I hope it will be useful for all of you. Remember – be a reasonable. Use short log entries for business activity monitoring and keep them far from technical details. A statement “Rejecting message because validation error” is sufficient for 95% of people. The remaining 5% is involved in development but for these you have a separate log.

I hope you like the idea of best practices and you would like to see more similar entries. If you feel yourself more experienced than I or you simply prefer a different approach and would like share your ideas – do that. It will be pleasure to discuss here or link to your reply on other blog.

Why I would use Aries Blueprint instead of Spring?

That’s good question. Let me answer. First of all Aries runs fine with OSGi. With OSGi you have full modularity and extensive life cycle for your deployment units. Spring Framework is cool and offer you only life cycle for your beans. Just imagine that you don’t have to assembly whole webapp every time when your DAO implementation is changed. Also Spring have some issues with custom namespaces and supports only one way of hadling it – fail fast. If you are interested in details you can finds some answers on Guillaume Nodet blog in post about custom namespace handlers.
Of course you can still run Spring-DM under OSGi or select some Spring Source product. For me, blueprint fits OSGi much better.

How to run OSGi under Tomcat

As you (may) know OSGi is an module layer. Tomcat is an servlet container. If you wish run something under Tomcat that must be an WAR. So to start using OSGi under Tomcat I’ll simply embed it inside an war. Because I would expose a servlets registered under OSGi to be accessible throught tomcat connector I’ll also use additional proxy service. So there are two different solutions one is Equinox Servlet Bridge and Felix Http Bridge. Both works fine. For this post I’ve selected Felix artifacts.

Starting Framework is really simple, you just need an instance of ServletContextListener which will start the framework.

public class StartupListener implements ServletContextListener {

    private Logger logger = LoggerFactory.getLogger(StartupListener.class);

    private FrameworkService service;

    public void contextInitialized(ServletContextEvent event) {
        logger.info("Starting felix framework");

        this.service = new FrameworkService(event.getServletContext());
        this.service.start();
    }

    public void contextDestroyed(ServletContextEvent event) {
        logger.info("Framework shutdown");

        this.service.stop();
    }
}

I could finish my post here, but I’ve meet multiple problems. I will describe them here to not lost them in future.

FrameworkService and ProvisioningActivator

First of all, I would like to install some bundles after framework startup. Starting only Felix is not fun at all. We need modules! To get this part done we need to use an specific Felix configuration option called felix.systembundle.activators. It allows to pass BundleActivator instances using different classloader/different context than OSGi framework execution. By this way we can simply access resources embeded in WAR. I know it is not really nice solution, but I wanted to keep my demo simple. Just see the ProvisioningActivator code below. We use our servlet context during bundle activation!

public class ProvisionActivator implements BundleActivator {

    private final ServletContext servletContext;

    private static transient Logger logger = Logger.getLogger(ProvisionActivator.class.getName());

    public ProvisionActivator(ServletContext servletContext) {
        this.servletContext = servletContext;
    }

    public void start(BundleContext context) throws Exception {
        servletContext.setAttribute(BundleContext.class.getName(), context);

        ArrayList<Bundle> installed = new ArrayList<Bundle>();
        for (URL url : findBundles()) {
            Bundle bundle = context.installBundle(url.getFile(), url.openStream());
            installed.add(bundle);
        }

        for (Bundle bundle : installed) {
            try {
                bundle.start();
            } catch (Exception e) {
                logger.warning("Unable to start bundle " + bundle.getSymbolicName() + ". " + e);
            }
        }
    }

    public void stop(BundleContext context) throws Exception {
    }

    private List<URL> findBundles() throws Exception {
        List<URL> list = new ArrayList<URL>();

        Set paths = this.servletContext.getResourcePaths("/WEB-INF/bundles/");
        logger.info("List of entries in /WEB-INF/bundles/ " + paths);
        for (Object o : paths) {
            String name = (String)o;
            if (name.endsWith(".jar")) {
                URL url = this.servletContext.getResource(name);
                if (url != null) {
                    list.add(url);
                }
            }
        }

        return list;
    }
}

Now we need proxy servlet and proxy startup listener. First receives calls from browser and forward its to OSGi servlets, second delivers some servlet events from war to OSGi. The setup is really simple:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="

http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

    version="2.5">

    <display-name>Aries WebApp</display-name>

    <listener>
        <listener-class>org.code_house.workshop.aries.war.StartupListener</listener-class><!-- This part starts the Framework -->
    </listener>

    <listener>
        <listener-class>org.apache.felix.http.proxy.ProxyListener</listener-class>
    </listener>

    <servlet>
        <servlet-name>proxy</servlet-name>
        <servlet-class>org.apache.felix.http.proxy.ProxyServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>proxy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

</web-app>

Ok, having the framework running is great, but now we would like to use Felix WebConsole to inspect environment we run. For that we need another important improvement. If you have done some webapps you know that servlet api should not be included in WARs. We need respect same rule in this case. We can not install servlet api as OSGi bundle because ProxyServlet uses WAR classloader, it is not part of any bundle. Because of that we need configure framework to load javax.servlet and javax.servlet.http packages from parent classloader. Just remember to add them in org.osgi.framework.system.packages configuration property.
From OSGi point of view we need an bridge which registers HttpService. Bot OSGi part and proxy part are linked. To get everything running you need both of them.

Now we are close to run everything. What we need to remember? Well under OSGi we have to handle dependencies just like under Tomcat, so I’ll install following artifacts:

• org.apache.aries.blueprint – blueprint-api, blueprint-core, to support declarative services
• org.apache.aries.proxy – proxy-api, proxy-impl, these two are blueprint dependencies
• org.apache.felix – http bridge, to link OSGi servlets with Proxy Servlet
• org.ops4j.pax.logging – pax-logging-api, pax-logging-service, just to see what happens
• org.apache.felix – webconsole, to track environment

The basic setup can be really tiny. One thing I did not solve is proper logging. Because pax-logging-service uses log4j and some containers also do there is small conflict between those two. I did not investigate this realy deeply, but I suppose that there is need to put them into system packages list.

Summary

Running OSGi under Tomcat is not hard part. Actually many of providers do that, for example Atlassian have own extension system build on top of OSGi. If your product need an extreme extensibility, then this post is for you. If you will build it correctly then updates will work right after the update without need to restart whole web application.

I hope you enjoyed this part. If you are looking for source code – visit github. The code contains few modules. After build you can drop a war/target/webapp-1.0.0.SNAPSHOT.war into tomcat webapps directory. You can run mvn jetty:run-war to see same effect. After that you will be able to access Felix WebConsole at http://localhost:8080/webapp-1.0.0.SNAPSHOT/system/console. The default user and password is admin. Have fun!

Enabling AspectJ

Byte code manipulation requires access to class resource (.class file). It can be obtained from class loader which was used to load the class. Under Tomcat it’s easy. Anywhere you are, you can use MyClass.class.getClassLoader() and you will access web application class loader. But how to handle it under OSGi, where every bundle have own class loader? Equinox supports technic called hooks. It allows us, the developers, to extend framework in more declarative way. Hooks became very useful and since OSGi 4.3 release all certified frameworks will support few:

• Resolver Hook
• Bundle Hook
• Service Hook
• and finally Weaving Hook

The core difference between hooks in Equinox and in OSGi 4.3 is how they are registered. OSGi 4.3 allows to register hooks as typical services. In older Equinox they’re loaded from framework configuration or they are discovered by classpath scanning (they must be attached to Eqinox bundle as fragments). So whole trick is to start framework with hooks JARs. Also, to make aspects works, in older version, AspectJ must be loaded before any woven class, but that’s logical. You can’t weave classes when they already loaded and cached by JVM.

Enabling in Karaf

Because actual version of Karaf (2.2.4) still works with OSGi 4.2 we’ll use older way to enable aspects. First of all, before launch we’ll change default framework. By default Karaf distribution uses Felix as OSGi framework. Open the etc/config.properties and change the karaf.framework property to equinox.

karaf.framework=equinox

If you are interested in different versions of same framework, you can simply hack this file because the karaf.framework is used to look up another property. Few lines below in configuration file you can see:

karaf.framework.equinox=${karaf.default.repository}/org/eclipse/osgi/3.6.2.R36x_v20110210/osgi-3.6.2.R36x_v20110210.jar
karaf.framework.felix=${karaf.default.repository}/org/apache/felix/org.apache.felix.framework/3.0.9/org.apache.felix.framework-3.0.9.jar

Framework JAR is located by expression karaf.framework.${karaf.framework}. But that’s only a note for curious people.

Once we switched to Equinox we have only few steps left. First of all we need to install aspectj and weaving hook. Last part is example aspects. I had problem to locate fresh version of Weaving hook because project was moved from Equinox Incubator to Equinox Bundles. We need download whole Equinox SDK to grab following artifacts from plugins directory:

• org.eclipse.equinox.weaving.aspectj_1.0.1.v20110502.jar
• org.eclipse.equinox.weaving.caching_1.0.100.v20110502.jar
• org.eclipse.equinox.weaving.hook_1.0.100.v20110502.jar

I copied these artifacts to karaf home directory except org.eclipse.equinox.weaving.hook. It goes to lib directory, otherwise hook won’t be discovered. That’s because hook discovery is done by property file lookup. The lookup uses framework class loader and in Karaf case it is URLClassLoader with lib/ entries and framework archive.

In addition we’ll need also AspectJ runtime. We’ll install it from ServiceMix bundles repository but it will be installed directly from maven. No additional download steep need. After that we can launch bin/karaf and start installing artifacts:

~/tools/apache-karaf-2.2.4-switch$ ./bin/karaf

        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/         


  Apache Karaf (2.2.4)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
karaf@root> install file:lib/org.eclipse.equinox.weaving.hook_1.0.100.v20110502.jar
Bundle ID: 49
karaf@root> install file:org.eclipse.equinox.weaving.aspectj_1.0.1.v20110502.jar
Bundle ID: 50
karaf@root> install file:org.eclipse.equinox.weaving.caching_1.0.100.v20110502.jar
Bundle ID: 51
karaf@root> install mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.aspectj/1.6.8._2
Bundle ID: 52
karaf@root> list
[  49] [Resolved   ] [            ] [   60] Aspect Weaving Hooks Plug-in (Incubation) (1.0.100.v20110502)
                                       Hosts: 0
[  50] [Active     ] [            ] [   60] WeavingService Plug-in (Incubation) (1.0.1.v20110502)
[  51] [Active     ] [            ] [   60] Standard Caching Service for Equinox Aspects (Incubation) (1.0.100.v20110502)
[  52] [Active     ] [            ] [   60] Apache ServiceMix :: Bundles :: aspectj (1.6.8.2)

To resolve correctly fragment bundle and connect it with equinox system bundle an restart may be needed. I recommend to restart, because it is the best way to connect everything together. Optionally you may set start level to be lower than default – 60. But for test purposes it may be leaved as is.

Running aspects

After installing all stuff it would be nice to run some aspects, isn’t? If we have environment ready to handle byte code manipulation it would be nice to use it. As an example Aspect I will use char counter. After writing to PrintStream instance it will write information how many characters was writen and to which stream. I don’t know AspectJ syntax so it might not be optimal – feedback is welcome.

package org.code_house.workshop.karaf.aspect.aspectj;

import java.io.PrintStream;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;;

public aspect HelloAspect {

	after(String msg, PrintStream stream) : // after call
		call(void PrintStream.println(String)) // println
		&& !within(HelloAspect)  // not from Aspect
		&& args(msg)  // with String attribute
		&& target(stream) { // and PrintStream as a target
		stream.println("You just wrote " + msg.length() + " chars to " + stream); // display message
	}
}

Because we going to weave classes during load time we need META-INF/aop.xml file to let discover our aspects. Contents of file are really simple and points to aspect class name. Also it worth to notify to be careful with AspectJ version. I’ve got an error:

BCException: Unable to continue, this version of AspectJ supports classes built with weaver version 6.0 but the class org.code_house.workshop.karaf.aspect.aspectj.HelloAspect is version 7.0

The root cause is version mismatch between runtime and compile time. I used version 1.6.11 to compiler and 1.6.8 to run. After aligning versions to 1.6.8 it started working again.
Second, important thing is a specific manifest entry Eclipse-SupplementBundle. It says which bundle is enhanced by aspects contained inside declaring bundle. I’ve put org.code-house.workshop.karaf.aspect.bundle because I going only to instrument one bundle. But value of this header might be an wildcard. Second option is to add Require-Bundle header pointing to org.aspectj.runtime.

So the last step is to install our artifacts and check if they’re runnign correctly. Let’s do that.

karaf@root> install mvn:org.code-house.workshop.karaf.aspect/aspectj/1.0.0.SNAPSHOT
Bundle ID: 53
karaf@root> install mvn:org.code-house.workshop.karaf.aspect/bundle/1.0.0.SNAPSHOT
Bundle ID: 54
karaf@root>  list
[  53] [Active     ] [            ] [   60] Code-House :: Workshop :: Karaf :: Aspect :: AspectJ (1.0.0.SNAPSHOT)
[  54] [Active     ] [            ] [   60] Code-House :: Workshop :: Karaf :: Aspect :: Bundle (1.0.0.SNAPSHOT)

karaf@root> start 53 54
Starting org.code-house.workshop.karaf.aspect.bundle
You just wrote 52 chars to org.apache.felix.gogo.runtime.threadio.ThreadPrintStream@327800e9

Summary

Whole code used to write this post is publically available on GitHub. Remember to use Aspects carefully, because they might change behaviour on whole environment, especially when you use centralized load time weaving. It’s worth to add excludes in your aop.xml file to don’t w enhance packages different than we really wish to instrument.
If you are interested in AspectJ usage with OSGi 4.3, you can follow this topic.

In his example Marcelo used broker feature called Exclusive Consumers. It lets send messages only to one consumer and if it fails then second consumer gets all messages. I think it is not the best idea if we have many messages to process. Why we wouldn’t use few consumers with preserved message order? Well, I was sure it is not possible, but during last training I’ve found solution.

Broker configuration

So how to force ActiveMQ to preserve message order? It’s really simple, we just need to change dispatch policy for destination. We can do this for all queues or only for selected.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:amq="http://activemq.apache.org/schema/core">

    <broker xmlns="http://activemq.apache.org/schema/core">
        <destinationPolicy>
            <policyMap>
                <policyEntries>
                    <policyEntry queue=">"><!-- Please refer 2nd part of this post -->
                        <dispatchPolicy>
                            <strictOrderDispatchPolicy />
                        </dispatchPolicy>
                    </policyEntry>
                </policyEntries>
            </policyMap>
        </destinationPolicy>
    </broker>
</beans>

After this consumers should receive messages in same order like they were sent from producer. You can find example code on github: example-activemq-ordered. You can run all from maven:

cd broker1; mvn activemq:run
cd broker2; mvn activemq:run
cd consumer; mvn camel:run
cd consumer; mvn camel:run
cd producer; mvn camel:run

Upgrade

After posting update about this blog post to Twitter Dejan Bosanac send me fewupdates. He is co-author of ActiveMQ in Action so his knowledge is much more deeper than mine.
First of all I mixed XML syntax. strictOrderDispatchPolicy is handled by topics, not queues. For second destination type strict order is turned on by strictOrderDispatch attribute set to true for policyEntry element. This preserves order but, as Dejan wrote, it will broke round robin and all messages will go to only one consumer, as in previous example given by Marcelo.

Also, Marcelo published second post about Message Groups which allows to preserve order and have multiple concurrent consumers on queue.

Felix WebConsole

As response for problems with lack of common tool, available from browser a project Felix WebConsole was created. This is a subproject of Felix’a. In its assumptions Felix WebConsole should let easily extend itself through the use of mechanisms known from the core OSGi – that is, services. It should also let change look and feel and localize the tool. All these assumptions was covered, but number of extensions for Felix WebConsole do not grow like mushrooms after the rain.
The question is, why? Now, in its simplicity Felix WebConsole make difficult creation of more complex extensions such as JMX. The problem is that our extension is only a servlet. From one hand it’s too much to put a link in list of bundles, on the other hand it is too little to make a few pages. If we’ll try we’ll begin to implement the second Struts framework based on servlets.
Project team do not make things easier because it puts on the “lightness” console. It is expected to deploy console on mobile devices too.

Karaf WebConsol as alternative

Apache Karaf WebConsole is brand new project, which was made few months ago. After dynamic incubation phase, which maybe was too short, it was moved to sub-project of Karaf. Similar as precursor it points to lightness but also points to collaboration with other web frameworks, in this case it is another ASF project – the Apache Wicket. Through its use we obtained far-reaching component model. It means that you may add link to menu and style it with fragment CSS (without fragment bundle). You may add new tab with content or simply put another widget to dashboard. All these things you may see right after logging into console.
All these extension won’t be possible without Wicket and Pax-Wicket. Thanks to huge amount of work made by Andreas Pieber on second project. Everything is stable and works as fast as Felix WebConsole.

Architecture of Karaf WebConsole

As I meintoned before, WebConsole uses Pax-Wicket and Wicket as presentation layer (we don’t count Java Script libraries). Most of extensions uses also blueprint to register services. There is no problem, similary like in case of Felix WebConsole, to use Spring DM or declarative services. Everything works with Pax-Web, but it should be possible to run it with any HttpService.
Whats’s more, an experimental branch of pax-wicket which I worked on previously named jsr330 let to use same components in a traditional container like is Tomcat. This means that the administrative tool went beyond the OSGi framework and will allow creation of multi-modular consoles, also in a traditional environment.

Extensions

New elements who are added to Karaf WebConsole are typically Wicket components or they are converted to them. Let see how to add new element to navigation:

package org.apache.karaf.webconsole.blueprint.internal.navigation;

import java.util.ArrayList;
import java.util.List;

import org.apache.karaf.webconsole.blueprint.internal.BlueprintPage;
import org.apache.karaf.webconsole.core.navigation.NavigationProvider;
import org.apache.wicket.Page;
import org.apache.wicket.markup.html.basic.Label;
import org.apache.wicket.markup.html.link.BookmarkablePageLink;
import org.apache.wicket.markup.html.link.Link;

public class BlueprintNavigationProvider implements NavigationProvider {

    public List<Link<Page>> getItems(String componentId, String labelId) {
        List<Link<Page>> items = new ArrayList<Link<Page>>();

        Link<Page> link = new BookmarkablePageLink<Page>(componentId, BlueprintPage.class);
        link.add(new Label(labelId, "Blueprint"));
        items.add(link);

        return items;
    }

}

Interface org.apache.karaf.webconsole.core.navigation.NavigationProvider is universal supplier of navigation elements. In web application it’s mostly about links. Now, when we have implementation we need to submit it into registry to let use it. In this particular example we going to use blueprint, but it might be a standard activator or any other declarative way as well.

<?xml version="1.0" encoding="utf-8" ?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <service ref="provider" interface="org.apache.karaf.webconsole.core.navigation.NavigationProvider">
        <service-properties>
            <entry key="extends" value="osgi" />
        </service-properties>

    </service>

    <bean id="provider" class="org.apache.karaf.webconsole.blueprint.internal.navigation.BlueprintNavigationProvider" />

</blueprint>

Fragment above will cause addition of BlueprintPage as child of OSGi menu, because we set extends property. Result of execution you may see on attached picture.

Navigation is only example, remember – you have much more possibilities:

• org.apache.karaf.webconsole.core.brand.BrandProvider – lets to change design (without fragment bundles)
• org.apache.karaf.webconsole.core.navigation.ConsoleTabProvider – causes addition of new tab in navigation
• org.apache.karaf.webconsole.core.navigation.SidebarProvider – adds new elements on left side
• org.apache.karaf.webconsole.core.widget.WidgetProvider – lets to publish new panels with content
• org.apache.karaf.webconsole.osgi.bundle.IActionProvider – adds specific link to bundle list
• org.apache.karaf.webconsole.osgi.bundle.IColumnProvider – adds column to bundle list
• org.apache.karaf.webconsole.osgi.bundle.IDecorationProvider – adds icon bundle list

Felix WebConsole

W odpowiedzi na problemy z brakiem tego typu narzędzia, dostępnego z poziomu przeglądarki powstał projekt Felix WebConsole. Jest to podprojekt dobrze znanego w światku Felix’a. W swych założeniach Felix WebConsole ma pozwalać na łatwe rozszerzanie poprzez użycie mechanizmów znanych z core osgi – czyli usług. Ma również pozwalać na łatwą zmianę wyglądu oraz internacjonalizację. Wszystkie te założenia zostały spełnione, jednak ilość rozszerzeń do Felix WebConsole nie rośnie niczym grzyby po deszczu.
Nasuwa się pytanie, dlaczego? Otóż, w swej prostocie Felix WebConsole utrudnia tworzenie bardziej złożonych rozszerzeń takich jak np. JMX. Problem polega na tym, że nasze rozszerzenie to tylko i aż servlet. Jest to z jednej strony zbyt dużo by dorzucić link np. do listy wiązek a z drugiej strony zbyt mało by zrobić kilka podstron, ponieważ zaczniemy implementować drugiego strutsa.
Sprawy nie ułatwia sam zespół projektu, który stawia na “lekkość” konsoli, co ma pozwalać na jej uruchomienie również na urządzeniach mobilnych.

Karaf WebConsole jako alternatywa

Apache Karaf WebConsole to nowy projekt, który powstał kilka miesięcy temu. Po bardzo dynamicznej fazie inkubacji, która trwała być może zbyt krótko, został powołany do życia jako pod-projekt Karafa. Karaf WebConsole tak jak i poprzednik stawia na lekkość, ale zakłada współpracę z frameworkami webowymi, w tym przypadku jest to kolejny projekt ASF – Apache Wicket. Dzięki jego użyciu uzyskaliśmy daleko idącą komponentowość. To znaczy, że możesz dodać link do menu oraz określić jego wygląd przy pomocy CSS. Możesz dodać nową zakładkę ze stałą treścią bądź po prostu “widget” do ekranu powitalnego, który zobaczysz tuż po zalogowaniu korzystając z usług OSGi.
Wszystkie te rozszerzenia nie były by możliwe gdyby nie Wicket oraz Pax-Wicket. Dzięki ogromowi pracy, który Andreas Pieber włożył w rozwój tego drugiego projektu całość działa stabilnie oraz równie szybko, co Felix WebConsole.

Architektura Karaf WebConsole

Tak jak już wspomiałem WebConsola wykorzystuje Pax-Wicket oraz Wicket do prezentacji (nie licząc bibliotek Java Script). Większość rozszerzeń wykorzystuje również blueprint do tego by się rejestrować. Nie ma jednak problemu, podobnie jak w przypadku Felix WebConsole, aby użyć Spring DM lub declarative services. Całość działa z Pax-Web, ale powinno być możliwe użycie dowolnego HttpService.
Co więcej eksperymentalny branch pax-wicket nad którym pracowałem wcześniej nazwany jsr330 umożliwi używanie tych samych komponentów również w tradycyjnym kontenerze jakim jest Tomcat. To znaczy, że narzędzie administracyjne wykraczało by poza ramy OSGi umożliwiając tworzenie wielo-modułowych konsoli również w tradycyjnym środowisku.

Rozszerzenia

Nowe elementy, które są dodawane do Karaf WebConsole są zazwyczaj komponentami Wicketa bądź są przekształcane na nie. Przyjrzyjmy się w jaki sposób dodać nowy element do nawigacji:

package org.apache.karaf.webconsole.blueprint.internal.navigation;

import java.util.ArrayList;
import java.util.List;

import org.apache.karaf.webconsole.blueprint.internal.BlueprintPage;
import org.apache.karaf.webconsole.core.navigation.NavigationProvider;
import org.apache.wicket.Page;
import org.apache.wicket.markup.html.basic.Label;
import org.apache.wicket.markup.html.link.BookmarkablePageLink;
import org.apache.wicket.markup.html.link.Link;

public class BlueprintNavigationProvider implements NavigationProvider {

    public List<Link<Page>> getItems(String componentId, String labelId) {
        List<Link<Page>> items = new ArrayList<Link<Page>>();

        Link<Page> link = new BookmarkablePageLink<Page>(componentId, BlueprintPage.class);
        link.add(new Label(labelId, "Blueprint"));
        items.add(link);

        return items;
    }

}

Interfejs org.apache.karaf.webconsole.core.navigation.NavigationProvider jest uniwersalnym dostawcą elementów nawigacyjnych. W aplikacji webowej sprowadza się to do linków. Teraz, gdy mamy implementację należy zgłosić usługę do rejestru tak by została ona użyta. W tym celu użyjemy blueprint, ale równie dobrze może to być standardowy aktywator bądź inny mechanizm declarative services.

<?xml version="1.0" encoding="utf-8" ?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <service ref="provider" interface="org.apache.karaf.webconsole.core.navigation.NavigationProvider">
        <service-properties>
            <entry key="extends" value="osgi" />
        </service-properties>

    </service>

    <bean id="provider" class="org.apache.karaf.webconsole.blueprint.internal.navigation.BlueprintNavigationProvider" />

</blueprint>

Powyższy kawałek spowoduje dodanie linku do BlueprintPage jako element menu OSGi, ponieważ podaliśmy wartość extends. Wynik działania powyżej.

Nawigacja to tylko przykład, pamiętaj - możliwości jest znacznie więcej:

• org.apache.karaf.webconsole.core.brand.BrandProvider – pozwala na zmianę wyglądu
• org.apache.karaf.webconsole.core.navigation.ConsoleTabProvider – dodaje nową zakładkę do konsoli
• org.apache.karaf.webconsole.core.navigation.SidebarProvider – dodaje elementy po lewej stronie ekranu
• org.apache.karaf.webconsole.core.widget.WidgetProvider – pozwala na dodawanie nowych paneli z treścią
• org.apache.karaf.webconsole.osgi.bundle.IActionProvider – dodaje link do listy wiązek
• org.apache.karaf.webconsole.osgi.bundle.IColumnProvider – dodaje kolumnę do listy wiązek
• org.apache.karaf.webconsole.osgi.bundle.IDecorationProvider – dodaje ikony do listy wiązek

Producing messages with JMS

Most of communication systems, whanever you will go have two different kinds of values, first – main and mainly used is body, second is typical metadata named headers or properties or parameters. JMS is not different, you can create different kinds of messages and set headers to them (in JMS world they’re named property, but I preffer header).
Let check messaging code we have:

// import declarations ...
public class JmsMessageSender implements MessageSender, InitializingBean {

	private ConnectionFactory connectionFactory;
	private Session session;
	private final String destination;
	private MessageProducer producer;

	public JmsMessageSender(String destination) {
		this.destination = destination;
	}

	public void sendMessage(String message, Map<String, Object> headers)
		throws Exception {

		if (session == null || producer == null) {
			afterPropertiesSet();
		}

		TextMessage jmsMsg = session.createTextMessage(message);
		for (String header : headers.keySet()) {
			jmsMsg.setObjectProperty(header, headers.get(header));
		}
		producer.send(jmsMsg);
	}

	public void afterPropertiesSet() throws Exception {
		Connection connection = connectionFactory.createConnection();
		session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
		Queue queue = session.createQueue(destination);
		producer = session.createProducer(queue);
	}

	// not important
}

First of all we inject connectionFactory using Spring configuration file. In line 20 we create text message, because we sending messages with String as content. Line 22 sets headers for message and finally sends it in line 24 using message producer created in lines 28-31. If we’ll look closer these lines we’ll see standard initalization code automatically called during bean creation by Spring. In line 29 we create session without transaction support and create producer to send messages. Connection factory is configured in XML with properties file to extract informations like broker url username and password.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

    <bean id="view" class="org.code_house.mom.producer.ProducerWindow">
        <property name="title" value="Bank Agent APP" />
    </bean>

    <bean id="controller" class="org.code_house.mom.producer.ProducerController">
        <constructor-arg ref="view" />
        <property name="messageSender">
            <bean class="org.code_house.mom.producer.JmsMessageSender">
                <constructor-arg value="MOM.Incoming" />
                <property name="connectionFactory" ref="connectionFactory" />
            </bean>
        </property>
        <property name="mapper" ref="mapper" />
    </bean>

    <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="${url}" />
        <property name="userName" value="${user}" />
        <property name="password" value="${pass}" />
    </bean>

    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="location" value="classpath:activemq.properties" />
    </bean>

    <bean id="mapper" class="org.codehaus.jackson.map.ObjectMapper" />

</beans>

I decided to use JSON over XML. Regarding last post about data structures it is not the best choice but it is very simple. So don’t treat it as reference implementation. I just wish to don’t use JAXB annotations.

Headers

Headers are common thing for routing. This is main reason why I allow to provide headers as parameter to sendMessage method. In many cases it is better to use headers or even extract headers from body of message in one endpoint to reduce number of content reads. Example how to use headers for routing we’ll see in next part about Apache Camel.

Just as a note types of headers supported by JMS spec:

• Boolean
• Byte
• Short
• Int
• Long
• Float
• Double
• String
• Object

We can get or set headers using getTypeProperty(String name) or setTypeProperty(String name, Type value). Remember that headers of type “object” set by setObjectProperty must be serializable, otherwise they will be dropped before sending.

Producer application

As I said at begining of the post I spent two days on Swing hacks. I injected two additional depentencies to this module – mig layout and better beans binding. First is responsible for frame layout, second for interactions between model and Swing controls. Whole application is simple form. All informations are displayed in status bar at bottom of the window, rest is taken by message area and combo boxes.

I have say, that binding framework is cool and reduced number of code lines I had to write without it. If you are interested in exact code structure, please go to producer module in mom-sample github repository. Because it is not in area of this post I will not write more about desktop implementation details.

For these who wish run sample (I belive you would do that) – after executing

mvn clean install

You can simply execute target/producer.jar by doulbe click. This is fat-jar with all dependencies needed by producer application.

Tabelka poniżej prezentuje zawartość przeniesioną ze strony Suna. Zawiera ona 4 najpopularniejsze wzorce. Dwa najczęściej spotykane w internecie to Venetian Blind oraz Garden of Eden ze względu na to, że są bardzo podatne na ponowne użycie.

Przykłady

Russian Doll

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://schemas.sun.com/point/russiandoll"
    xmlns:tns="http://schemas.sun.com/point/russiandoll"
    elementFormDefault="qualified">

    <xsd:element name="Line">
	<xsd:complexType>
	    <xsd:sequence>
		<xsd:element name="PointA">
		    <xsd:complexType>
			<xsd:attribute name="x" type="xsd:integer"/>
			<xsd:attribute name="y" type="xsd:integer"/>
		    </xsd:complexType>
		</xsd:element>
		<xsd:element name="PointB">
		    <xsd:complexType>
			<xsd:attribute name="x" type="xsd:integer"/>
			<xsd:attribute name="y" type="xsd:integer"/>
		    </xsd:complexType>
		</xsd:element>
	    </xsd:sequence>
	</xsd:complexType>
    </xsd:element>
</xsd:schema>

Salami Slice

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://schemas.sun.com/point/salami"
    xmlns:tns="http://schemas.sun.com/point/salami"
    xmlns="http://schemas.sun.com/point/salami"
    elementFormDefault="qualified">

    <xsd:element name="PointA">
	<xsd:complexType>
	    <xsd:attribute name="x" type="xsd:integer"/>
	    <xsd:attribute name="y" type="xsd:integer"/>
    	</xsd:complexType>
    </xsd:element>

    <xsd:element name="PointB">
	<xsd:complexType>
	    <xsd:attribute name="x" type="xsd:integer"/>
	    <xsd:attribute name="y" type="xsd:integer"/>
	</xsd:complexType>
    </xsd:element>

    <xsd:element name="Line">
    	<xsd:complexType>
	    <xsd:sequence>
		<xsd:element ref="PointA"/>
		<xsd:element ref="PointB"/>
	    </xsd:sequence>
	</xsd:complexType>
    </xsd:element>
</xsd:schema>

Venetian Blind

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://schemas.sun.com/point/venetianblind"
    xmlns:tns="http://schemas.sun.com/point/venetianblind"
    xmlns="http://schemas.sun.com/point/venetianblind"
    elementFormDefault="qualified">

    <xsd:complexType name="PointType">
	<xsd:attribute name="x" type="xsd:integer"/>
	<xsd:attribute name="y" type="xsd:integer"/>
    </xsd:complexType>

    <xsd:element name="Line">
	<xsd:complexType>
	    <xsd:sequence>
		<xsd:element name="PointA" type="PointType"/>
		<xsd:element name="PointB" type="PointType"/>
	    </xsd:sequence>
	</xsd:complexType>
    </xsd:element>
</xsd:schema>

Garden of Eden

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://schemas.sun.com/point/gardenofeden"
    xmlns="http://schemas.sun.com/point/gardenofeden"
    elementFormDefault="qualified">

    <xsd:complexType name="PointType">
	<xsd:attribute name="x" type="xsd:integer"/>
	<xsd:attribute name="y" type="xsd:integer"/>
    </xsd:complexType>

    <xsd:complexType name="LineType">
	<xsd:sequence>
	    <xsd:element ref="PointA"/>
	    <xsd:element ref="PointB"/>
	</xsd:sequence>
    </xsd:complexType>

    <xsd:element name="PointA" type="PointType"/>

    <xsd:element name="PointB" type="PointType"/>

    <xsd:element name="Line" type="LineType"/>
</xsd:schema>

The data structures are very important in middleware world. Because we often connect multiple systems we need to define an “domain model” for integration. The domain model means that objects we share between all systems are well known, well defined, well understand in multiple teams often provided by multiple vendors. Let see what does it means in practice.

Well known

If you talk with business guys you have to use same terms with programmers. You might be mediator but not the translator. As integration team member mediate correct shape of solution but don’t became a translator between business divisions and developers (unless you are business analitic). All people should use same terms to minimalise problems with number of definitions. That’s first step of multiple projects, not only integration. If you look for deeper knowledge of domain definitions check a “Domain Driven Design” book written by Eric Evans and published in 2003. Ok, maybe business is not always part of integration project, but you communicate systems used by people, isn’t?

Well defined

You have names and scopes for your classes and objects. Probably you have 90% of fields that will be defined in them. Remember to don’t put too much informations from one system to domain model. Domain model is not list of entities from one system. Make sure that you don’t share database identifier from one system to second. Identifier should be business, for example most of clients might be identified by personal document, most of companies can be identified by tax id, not by database sequence. For future reasons try to extract atomic values, like for databases. With atomic values you will have less text processing to extract specific data and less code to maintain.

Well understand

That’s case for distributed teams. Usually every team have own parts of software to do and every team plays different game. Someone else produces messages, someone consumes them, this is place when you’ll have small wars. Make sure that data structures you all have to share match common needs, that defined identifiers are fine for different systems too. I met multiple situations when system analytics from two companies spent lots of hours on phone defining field constraints. Don’t follow this path.

Whole integration project is about to fail in 95% cases – if you will not have data structures. Ok, we know that proper structure is key for integration. Second important point in data is representation. I don’t going to talk about REST at all, but rather about format of serialization. We have number of options here, just look table below

There is number of different wire formats not listed here – for example Protobuf, EDI which match this scenario too. I don’t count them (even if I should) because first is not well supported in many languages, second is rather legacy format not well for new systems.

Structures used in MOM

Like in most cases, also with middleware we have some data structures. Because we going to process simple cash transactions we’ll have following classes:

• org.code_house.mom.domain.Transaction
• org.code_house.mom.domain.Client
• org.code_house.mom.domain.Money
• org.code_house.mom.domain.Money.Currency

Transaction

Every transaction will have unique identifier generated by UUID. Transaction will point to some Client and have assigned Money object.

Client

In our case client is very simple POJO which contains fields ID and name. For middleware purposes we going to use only ID. Name might be usefull for user interface operations.

Money

Because we going to transfer some money to client account from producer we have to use proper data structure for a “cash”. Few years ago Martin Fowler in his book “Patterns of Enterprise Application Architecture” defined a Money pattern which is suitable to handle money values. We have to remember that client account might be handled in different currency and we cannot send only amount information. We need a currency too.

That’s all for data structures. It was more about philosophy than about code, but don’t worry – in next part we going to write more. All needed classes you’ll find in git repository. You may download zip archive|tar archive if you don’t have git client.

What middleware is?

Middleware is a general term, about some software which is some kind of proxy between other systems. What for? – you could ask. Generally because communication from point to point is not the best to build bigger applications, and some components in middle of communication allows us to inject new logic without changing source systems. Could you imagine situation where you have a number of system producing messages and an number of consumers of these messages written in different languages? That’s typical case where middleware is going to be usefull.
There is number of middleware tools from various categories, in this post we’ll learn how to use ActiveMQ to build message oriented middleware. What does the MOM means? Generally that we have asynchronous communication without direct method invocations. Producer don’t know anything about consumer and vice versa. If you are interested in MOM – pick up “ActiveMQ in Action” book (written by commiters of ActiveMQ) from Manning Publications Co. where this term is described in greater detail.

The scenario

In our scenario we we’ll use number of queues, every client will have own queue and will consume messages only from this queue. The producer will send messages with header which will be used to determine client queue. In the middle we have Apache Camel which will process incoming messages and dispatch them to concrete client queues. Camel will also copy messages to log queue for audit processor (not listed on image).

As alternative I going to show you how to extract client ID from message body instead of forcing producer to use headers.

Setting up ActiveMQ

If you are Linux or MacOS user you could use brew package manager to install activemq using following command:

brew install activemq

Other users can download ActiveMQ package from project site.

Ok, we have ActiveMQ installed, in next steep we going to create an test instance of activemq where we’ll hack configuration. To do this execute following command:

activemq-admin create mom

After execution of command you should get following directory structure

We don’t going to use all of these files, so in my set up I going to remove next configuration files:

• Because we don’t going to use SSL yet:
  • broker.ks
  • broker.ts
• Because we don’t use security yet:
  • credentials.properties
• Because we don’t going to use ActiveMQ webconsole:
  • jetty-realm.properties
  • jetty.xml

These files are unecessary at this moment in our setup.

Configuring ActiveMQ

Becase activemq-admin script creates dummy broker configuration we have to modify it a bit. Remember to put elements in XML file with alphabetic order. Since ActiveMQ 5.4 release all elements are ordered.. First of all we going to modify destinationPolicy element:

        <destinationPolicy>
            <policyMap>
                <policyEntries>
                    <policyEntry queue=">" optimizedDispatch="true" lazyDispatch="false" producerFlowControl="false" memoryLimit="12 mb" />
                    <policyEntry queue="MOM.Client.>" advisoryForDelivery="true" advisoryForConsumed="true" />
                </policyEntries>
            </policyMap>
        </destinationPolicy>

First policyEntry element disables producerFlowControl. In other words ActiveMQ will accept all messages sent by producer, even when the memory limit was exceeded. Messages that are not able to be put in memory will be persisted in store. By default ActiveMQ have producerFlowControl set to true, and broker will notify producer to wait untill there will be place in memory, eg. messages from queue will be consumed. Second entry turn on advisory messages for message delivery and consumption for MOM.Client.* queues. These advisory messages are sent when message was received from producer and was succesfully processed by consumer. ActiveMQ offers number of advisory topics and messages. Some of them are disabled, some other are enabled by default.

Second change in configuration file is predefined destinations.

        <destinations>
            <queue physicalName="MOM.Incoming" />
            <queue physicalName="MOM.Audit" />
        </destinations>

These destinations will be created when broker starts, even if there is no consumers or producers. After these changes we can start our broker with following command:

$ACTIVEMQ_HOME/bin/mom console

With VisualVM we can check which destinations are created by default. When you start monitoring tool simply select local process with org.apache.activemq.console.Main which should be displayer after execution of command listed above.

That’s all for ActiveMQ set up. If you have troubes with configuration changes, you can pick up all changes directly from git repository or download zip archive|tar archive if you don’t have git client.