UX-Bridge - Installation Guide

The UX-Bus is a message-oriented middleware (MOM) for exchanging messages among the participating components. Apache ActiveMQ is used as the message broker. The routing is configured using the integrated Apache Camel framework.

The UX-Bus forwards the sent messages to the configured end points. Thus the messages generated by FirstSpirit are directed to the corresponding adapter. After saving the data, this adapter generates a response, which is sent from the UX-Bus to a component in FirstSpirit server.

For information about installing the UX-Bus, refer to Section Installation of the UX-Bus.

These components have to be installed on the FirstSpirit server. The module’s main component is a service that generates messages, sends them to the UX-Bus, and receives responses from the bus.

Section Installing the FirstSpirit module describes how to install and configure the module.

The UX-Bridge API makes it possible to use UX-Bridge Service in custom modules. To do this, the uxbridge-module-api-<version>.jar and JDOM version 1.0 must be included in the class path. The service can be accessed as follows:

UxbService uxbService = context.getConnection().getService(UxbService.class);

Adapters form the interface to the various content repositories and ensure that the data is written to a repository. Since adapters depend on the repository used as well as on the data model, they are project-specific components.

The content repository or live repository is a data storage component which is filled by FirstSpirit and read out by web applications.

Here, an important paradigm of the UX-Bridge architecture is: The type and number of repositories is not specified, since, depending on the kind of task, different repositories may be more or less suitable (see UX-Bridge Whitepaper).

Thus the suitable content repository is to be selected and installed depending on the project requirements.

Standalone operation is the recommended operating mode for the UX-Bus. In this scenario, all essential components are decoupled from each other. Additionally, it is best suited for configuring high-availability scenarios.

Installation

The UX-Bus requires having at least Java 7 installed. For the exact system requirements, please refer to the provided Technical Data Sheet.

Make sure that the environment variable is set to JAVA_HOME. Also, JAVA_HOME/bin should be added to the path variables.

The UX-Bus is installed simply by unzipping the distribution (ux-bus.zip) delivered in conjunction with the module into an appropriate folder of your choice. This distribution is already configured to achieve good results in conjunction with the UX-Bridge. It is a pre-configured Apache ActiveMQ with integrated Apache Camel, in which the routes for the UX-Bus and the adapters were already configured.

The start scripts are in the bin folder. The activemq script can be used to start the UX-Bus. Proceeding from the program folder, where ActiveMQ is located:

The default configuration is used initially in this case. The configuration is in the conf folder and later will, of course, need to be adapted in line with your own requirements at a later point.

Testing the installation

As soon as the ActiveMQ bus has been started, a message to this effect should be logged on the console:

INFO ActiveMQ JMS Message Broker (ID:apple-s-Computer.local-51222-1140729837569-0:0) has started

Using the netstat tool, you can now check whether the bus can in fact be accessed and whether the port was configured correctly.

In the default configuration, the port is 61616; it should be adjusted in accordance with your own configuration.

To test it, simply execute the following line in the console:

Installation as service

Configurations as a Windows Service or Unix Service is recommended for productive implementation. This ensures that the standalone server is also started automatically after restarting the operating system.

For information about installing as a service, visit:
http://activemq.apache.org/run-broker.html

Operation of the UX-Bus as a module on a FirstSpirit server is recommended only if operational reasons make it impossible for you to install the UX-Bus as a standalone component, but you have access and administration rights for the FirstSpirit server. In this operating mode, warnings usually appear in the FirstSpirit server log which are a result of the UX-Bridge Service being started before the UX-Bus. More information about these warnings is available at the end of this subsection.

However, if points such as Back channel (WebApp → FirstSpirit), Clustering, and Failover will be included, the UX-Bus should be operated as a standalone server.

If you would like to operate the UX-Bus in this mode, please proceed as follows:

The UX-Bus is then ready for use.

For more information on the topic of web applications, refer to the FirstSpirit Documentation for Administrators.

In this operating mode, UX-Bridge Service is started before the UX-Bus. Since UX-Bridge Service attempts to connect to the UX-Bus directly after starting, the following error messages are issued repeatedly in the FirstSpirit server log. After all components are started, this message should no longer appear. If the message continues to appear, refer to the instructions in Section Error analysis.

WARN 20.07.2012 14:00:03.919 (org.apache.camel.component.jms.DefaultJmsMessageListenerContainer): Could not refresh JMS Connection for destination 'FS_OUT' - retrying in 5000 ms. Cause: Connection refused: connect

The UX-Bridge Service is the interface from FirstSpirit to the UX-Bus; it is used to send messages.

The service is very easy to configure:

XML tab

The configuration is carried out using a Spring XML DSL. For more information about syntax, visit http://camel.apache.org/spring.html.

The following is an example of the configuration for the sample application:

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

    <bean id="jms" class="org.apache.camel.component.jms.JmsComponent">
      <property name="connectionFactory">
        <bean class="org.apache.activemq.ActiveMQConnectionFactory">
          <property name="brokerURL" value="failover:(tcp://localhost:61616)?maxReconnectAttempts=2&amp;startupMaxReconnectAttempts=10" />
        </bean>
      </property>
    </bean>
    <bean id="pooledConnectionFactory" class="org.apache.activemq.pool.PooledConnectionFactory" destroy-method="stop">
      <property name="maxConnections" value="10" />
      <property name="maximumActive" value="500" />
      <property name="connectionFactory" ref="jmsConnectionFactory" />
    </bean>
    <bean id="jmsConfig" class="org.apache.camel.component.jms.JmsConfiguration">
      <property name="connectionFactory" ref="pooledConnectionFactory" />
      <property name="transacted" value="false" />
      <property name="concurrentConsumers" value="10" />
      <property name="deliveryPersistent" value="true" />
    </bean>
    <bean id="jmsConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
      <property name="brokerURL" value="failover:(tcp://localhost:61616)?maxReconnectAttempts=2&amp;startupMaxReconnectAttempts=10" />
    </bean>
    <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
      <property name="configuration" ref="jmsConfig" />
    </bean>
    <camelContext xmlns="http://camel.apache.org/schema/spring" id="camelContext" trace="false">
      <package>com.espirit.moddev.uxbridge.service</package>
      <template id="producerTemplate" />
      <endpoint id="FS-Out" uri="activemq:topic:FS_OUT"></endpoint>
      <onException>
        <exception>java.lang.Exception</exception>
        <handled>
          <constant>true</constant>
        </handled>
        <process ref="uxbExceptionProcessor" />
      </onException>
      <route id="Adapter-Statistics-Response-Route">
        <from uri="jms:topic:FS_IN" />
        <convertBodyTo type="com.espirit.moddev.uxbridge.api.v1.service.UXBEntity" />
        <bean ref="UxbServiceStatisticsResponseHandler" method="print" />
      </route>
    </camelContext>
    <bean id="UxbServiceStatisticsResponseHandler" class="com.espirit.moddev.uxbridge.service.UxbServiceStatisticsResponseHandler">
      <constructor-arg ref="camelContext" />
    </bean>
    <bean id="uxbExceptionProcessor" class="com.espirit.moddev.uxbridge.inline.UxbExceptionProcessor" />
  </beans>

For development and test purposes, the UX-Bridge Service can be configured without a running UX-Bus (refer also to Section Routing). If the UX-Bridge Service is unable to connect with a UX-Bus, it regularly logs a related report. If this occurs over an extended period of time, it may be difficult to read the log entries. Therefore, a dummy configuration can be created that is used to save all messages as files in a specific folder.

<?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-3.0.xsd
       http://camel.apache.org/schema/spring
       http://camel.apache.org/schema/spring/camel-spring.xsd">
    <camelContext xmlns="http://camel.apache.org/schema/spring" id="camelContext" trace="false">
      <package>com.espirit.moddev.uxbridge.service</package>
      <template id="producerTemplate" />
      <endpoint id="FS-Out" uri="file://log/uxb-messages"></endpoint>
      <onException>
        <exception>java.lang.Exception</exception>
        <handled>
          <constant>true</constant>
        </handled>
        <process ref="uxbExceptionProcessor" />
      </onException>
      <route id="Adapter-Statistics-Response-Route">
        <from uri="direct:in" />
        <convertBodyTo type="com.espirit.moddev.uxbridge.api.v1.service.UXBEntity" />
      </route>
    </camelContext>
    <bean id="uxbExceptionProcessor" class="com.espirit.moddev.uxbridge.inline.UxbExceptionProcessor" />
  </beans>

After the service has been reconfigured, it will have to be restarted in order to implement the changes.

In this example, the messages are saved in the folder <FS-Home>/log/uxb-messages/. However, these files are not deleted automatically, which can cause the folder to become quite large, depending on the number of messages sent. If a high volume of messages is expected, you should set up a way to regularly delete old messages.

Options tab

In the second tab of UXBService you can define whether the messages are to be sent asynchronously or synchronously. If the box is checked, the messages are sent asynchronously. A higher performance can be achieved by doing so, since, unlike with synchronous communication, there is no waiting for a response. This performance improvement can be very advantageous with large amounts of data.

Information on sent messages are saved internally in a cache file for timing purposes until a response is received from an adapter. The length of time that messages without a response are kept until they are removed from the cache can be defined using the Days to keep timings input window.

The Send status messages checkbox can be selected to configure whether the UX-Bridge sends another message to the bus at the start of and after generation so that it is possible to respond directly to these events in the adapter (see the UX-Bridge Developer Documentation for more information).

The Send project information message checkbox controls whether a message is sent with project information at the start of generation (see the UX-Bridge Developer Documentation for more information).

Figure 9. Options of the UX-Bridge Service

The routing is defined in the conf/camel.xml file in the installation directory of the UX-Bus. In the distribution provided, some default routes are already specified, so that no adjustments are required initially.

For details on configuring the routing, refer to Section Changing the routing.

If the UX-Bus was installed on the FirstSpirit server, please proceed with configuring the routes as follows.

For a description of the routes to be configured in FirstSpirit, refer to the UX-Bridge Developer Documentation.

The default output file for logging is data/activemq.log. If problems arise, this is the place to start troubleshooting. Logging can be configured in the conf/log4j.properties file in order to adapt the log level to the particular requirements, for instance. The INFO log level is used in the default configuration. The following are output on the console and in the log file:

log4j.rootLogger=INFO, console, logfile

Furthermore, you can define packages which are to use a different log level. In the default configuration these are:

log4j.logger.org.apache.activemq.spring=WARN
log4j.logger.org.apache.activemq.web.handler=WARN
log4j.logger.org.springframework=WARN
log4j.logger.org.apache.xbean=WARN
log4j.logger.org.apache.camel=INFO

For debugging purposes, the log level can then be adjusted, for example, by replacing the respective line. Thus for the debug level:

log4j.rootLogger=DEBUG, console, logfile

In this case, you should be aware that many more messages will appear in debug mode, which makes it more difficult to filter out the relevant messages. To prevent this, you could leave the rootLogger configuration set to INFO and just set the configuration for the package to be investigated to DEBUG or even TRACE.

Thus:

log4j.logger.mein.eigenes.package=TRACE

In the delivered distribution it is sufficient to activate the following two lines in the <activemq>/conf/log4j.properties file in order to receive appropriate debug messages for the routing and processing of the messages:

#Or for more fine grained debug logging uncomment one of these
#log4j.logger.org.apache.activemq=DEBUG
#log4j.logger.org.apache.camel=DEBUG

LoggingBrokerPlugin provides even more detailed logging than log4j and, above all, enables you to obtain more information about what occurs in the UX-Bus. The plug-in can simply be added to <plugins> in the conf/activemq.xml configuration file:

...
<plugins>
 <loggingBrokerPlugin logAll="true"/>
</plugins>
...

More detailed explanations and other attributes are included in the Apache ActiveMQ documentation: http://activemq.apache.org/logging-interceptor.html

Logging of the UX-Bus helps in the event of errors and problems on the broker. However, if errors arise outside of the UX-Bus, logging should also be possible to quickly remedy the problems. Problems can arise at all clients linked to the UX-Bus. This includes UX-Bridge Service and the implemented adapters.

The logging tool used by UX-Bridge Service is log4j, which is made available by FirstSpirit API. The logging configuration used by FirstSpirit server is also used. To retain DEBUG messages for the UX-Bridge Service, you only need to activate DEBUG logging for the FirstSpirit server. To do so select the item Configuration → Logging under Server Monitoring on the FirstSpirit server. Edit the active configuration and change the first line as follows.

log4j.rootCategory=DEBUG, fs

The log level is adjusted automatically after the configuration is saved.

Adapters are used in the project, making the developer responsible for providing corresponding logging and documenting the usage accordingly.

KahaDB is used with activated persistence in the delivered distribution as the message store of the UX-Bus. If you also want to implement a disaster recovery plan for the message store, corresponding instructions are at http://activemq.apache.org/replicated-message-store.html.

For detailed instructions on configuring the message store, visit http://activemq.apache.org/persistence.html.

Backing up the message store

At delivery, KahaDB is configured for message persistence in the configuration (\conf\activemq.xml):

<broker>
 <persistenceAdapter>
  <kahaDB directory="${activemq.data}/kahadb"/>
 </persistenceAdapter>
</broker>

To create a backup of the KahaDB, the following steps are necessary:

For more information, visit: http://activemq.apache.org/how-do-i-back-up-kahadb.html

If a JDBC persistence of the JMS messages is used as an alternative to the Kaha persistence (http://activemq.apache.org/persistence.html), use the familiar database-specific backup mechanisms.

If the UX-Bus fails, it should be ensured that the performance of UX-Bridge Service and the adapters is not impaired. This means that either attempts are made to resend the messages later or the sending occurs directly via a second instance.

All clients logged in at the respective UX-Bus should be able to reconnect to another UX-Bus or attempt to establish a new connection after a certain waiting period. The failover protocol is provided for this purpose.

The failover protocol is already configured in the default configuration of UX-Bridge Service:

<property name="brokerURL" value="failover:(tcp://localhost:61616)"/>

In this case, the failover protocol ensures that if a connection is lost, attempts to establish a new connection are made at certain intervals. Here you can determine the various parameters yourself, such as how long the first waiting time should be, by what factor the waiting time should be increased with each attempt, and how long the maximum waiting time should be (initialReconnectDelay, backOffMultiplier, maxReconnectDelay).

The following is an example of a failover configuration with multiple UX-Bus instances:

<property name="brokerURL" value="failover:(tcp://broker1:61616, tcp://broker2:61616)?randomize=false"/>

In this case, broker1 is used to send the messages. If this fails, the messages are automatically sent by broker2.

If you use your own adapters, make sure that these also use the failover protocol to protect against dropped connections or failure of the UX-Bus.

The failover protocol is most useful when multiple UX-Bus instances are configured in a cluster (also refer to Section Master/slave operation). Now multiple UX-Bus instances can be specified, with which the failover protocol can connect. If the connection with a UX-Bus is lost, a connection to another UX-Bus is automatically established. For time-critical applications, the backup and backupPoolSize parameters can also be used to establish a certain number of backup connections that can be used immediately if an active connection is lost. The advantage is that the connection already exists in a standby state and does not have to be established in an emergency.

An alternative to using failover with clustering is to specify only one UX-Bus and, when configuring the UX-Bus, to arrange for the logged-in clients to automatically receive a list of every available UX-Bus with which they can establish a connection if there is a problem. The updateClusterClients and rebalanceClusterClients are provided for this purpose in the TransportConnector configuration of the UX-Bus.

For more information about the failover parameters, refer to the Apache ActiveMQ documentation at: http://activemq.apache.org/failover-transport-reference.html

Master/slave operation is a good way to increase the fail-safe performance. Here, an Apache ActiveMQ instance acts as master and one or more instances act as slave. The clients always send their requests to the master; only if the master fails does one of the slave instances become the new master and assumes its tasks. The messages will now be processed by this instance.

In contrast to this is the use of a network of brokers, for which all Apache ActiveMQ instances have equal rights.

In both cases, it is important to configure the Failover in the client.

Shared storage master/slave

In Shared storage master/slave clustering mode, the same KahaDB is used by multiple brokers for message persistence. Only one master can access the persistence, while the slaves are blocked. The slaves check at regular intervals whether they can get access to the persistence. If the master broker fails and shuts down, the slave broker receives access to the persistence. Only at this moment does the slave broker boot up completely and enable clients to establish a connection.

Two types of this shared persistence are possible:

One option is to use a relational database, in which the brokers store the data. One advantage of this method is that databases are backed up quickly and easily.

The second option is to access a shared file system on which the Apache ActiveMQ brokers then deposit the KahaDB. The only requirement of this file system is that there be a locking mechanism that ensures that there is always only one broker with access to the KahaDB.

To configure shared storage master/slave clustering, you only need to configure two brokers with access to the same persistence. To safeguard against failure, the brokers should run on different machines. The clients receive both broker addresses in the failover protocol, and if a master broker fails, a connection is immediately established with the new master broker. This broker accesses the data of the same persistence and thus is up to date. In each of the brokers, the persistence adapter has to be adjusted so that they all use the same directory.

<persistenceAdapter>
 <kahaDB directory="/sharedFileSystem/sharedBrokerData"/>
</persistenceAdapter>

For more information about configuration, refer to the official documentation at: http://activemq.apache.org/shared-file-system-master-slave.html

Be aware that this mode is prone to errors in combination with the file system. If the machine on which the file system is located fails, all brokers that are supposed to access it lose access to the persistence and, in the worst case, have to be shut down. If your own application is to be protected from errors in connection with the file system, choose a file system that is also distributed across multiple machines and remains functional if a machine fails.

A network of brokers consists of at least two different brokers, each of which has its own persistence store. In this case, it is not absolutely necessary for each broker to have the same messages (or all messages). One use case for this architecture is for load distribution.

In most usage scenarios, it is not necessary to use a network of brokers to distribute the load. Generally a single UX-Bus can process the anticipated amount of messages without any problems.

If load balancing is still desired, a client configuration would look something like this:

failover:(tcp://master1.IP:61616,tcp://master2.IP:61617)?randomize=true

master1 and master2 are a network of brokers; the messages are randomly distributed.

This architecture is best clarified by way of an example:

Broker A receives a message in Queue A and saves it in its own store. As long as no client at Broker B is listening for messages from Queue A, these messages are not needed at Broker B, which is why it does not receive them. As soon as a client of Broker B listens for messages from Queue A, Apache ActiveMQ ensures that Broker B also receives these messages in order to deliver them to the client.

Information about which clients are listening to which queues at which brokers is exchanged among the various brokers by means of what are called advisory messages. This way every broker always knows which messages are or are not of interest to other brokers.

When configuring individual brokers, you can also define filters for various messages or exclude other brokers from messages.

From the perspective of the client, this concerns the high availability of the brokers, but not the messages that are sent. The reason for this is that each broker has its own database for messages. If a broker fails, the messages of this broker are not distributed again until the broker has been restarted.

For more information on this topic, visit:
http://activemq.apache.org/networks-of-brokers.html and
http://activemq.apache.org/how-do-distributed-queues-work.html

By using one or more generation servers, the generation load can be decoupled from the FirstSpirit master server. In addition to generating the static pages, the generation server can also take over message generation. Messages continue to be sent via the UX-Bridge Service, which runs on the FirstSpirit master server.

In addition to the correct configuration of the UX-Bridge infrastructure, the configuration of the content repositories is also critical to ensure high availability.

Selection of a suitable repository is made for the specific project. Please consult the documentation for the repositories being used to learn more about high availability.

Adapters are implemented depending on the specific project. During development, the requirements regarding high availability have to be taken into account accordingly. In many scenarios, the requirements can be covered by multiple instances of the adapter and appropriate routing.

Apache ActiveMQ comes with options for managing and monitoring the application. For instance, there is the web console, which can be accessed at http://localhost:8161/admin as soon as it is activated. Where appropriate, localhost has to be replaced with the address of the machine where the UX-Bus is running.

For details on activating and configuring the web console, refer to the online documentation: http://activemq.apache.org/web-console.html

Above all, it is necessary that not everyone has unlimited access to the web console. In the conf/jetty.xml file, therefore, the line

<property name="authenticate" value="false" />

should be replaced with the line:

<property name="authenticate" value="true" />

Authorized users and their access data can then be entered in the file conf/jetty-realm.properties (the default user is admin with the username/password: admin/admin).

The web console offers simple functions for viewing information via the broker and providing a view of simple statistics. The display includes information about queues, topics, subscribers, connections, and the network. Additionally, there is a function for sending messages. This enables easy testing of applications without first writing extra code. The web console is intuitively operated, self-explanatory, and therefore not explained in greater detail here.

Some useful command line tools are also delivered with Apache ActiveMQ; these provide basic admin functions, including some functions for monitoring. Using the activemq-admin tool and the query parameter you can, for example, retrieve and read diverse broker, destination, connector and connection information. You can inspect messages using the browse parameter.

For a more detailed description of the scope of functions for all the options, refer to the official Apache ActiveMQ documentation: http://activemq.apache.org/activemq-command-line-tools-reference.html

Another option for monitoring is to use the JMX API. (Java Management Extensions). Some parameters of the above-mentioned command line tools (such as query) also use the JMX API to get information about brokers, queues, etc.

For details about configuring JMX, please refer to the Apache ActiveMQ documentation: http://activemq.apache.org/jmx.html

If the Apache ActiveMQ broker is configured to permit JMX connections, you can, for example, write your own help programs, which establish a JMX connection and read broker information.

To do so, refer to the official JMX API (http://docs.oracle.com/javase/7/docs/technotes/guides/jmx/spec.html) and the Apache ActiveMQ API, which provide additional functions (http://activemq.apache.org/maven/5.10.0/apidocs/). The BrokerViewMBean interface from the Apache ActiveMQ API is a good starting point for reading out the broker’s data using JMX.

The MBeans from Apache ActiveMQ are in the org.apache.activemq package and can be read out using tools such as JConsole, JVisualVM, or the like. For information about Apache Camel and the routes, refer to MBean org.apache.camel.

Via JMX Monitoring you can get information such as

In the event of an error, this can be used to gain valuable information via monitoring.

Advisory messages are used by Apache ActiveMQ to enable brokers to communicate with each other and to exchange information about queues, consumers, etc. To use these messages for your own monitoring purposes, for example, you can write your own application for listening to advisory messages.

For details on this, refer to the Apache ActiveMQ documentation: http://activemq.apache.org/advisory-message.html

UX-Bridge Service itself also provides an option for monitoring. Each message sent to the UX-Bus receives a time stamp when created. If an adapter processes the message, another time stamp is set as well as the status after the processing (ok/fail). In the schedule, a method can be invoked that queries the UX-Bridge Service and returns a list of messages, their processing time, and their status. To do so, a script action has to be added to the end of the schedule:

#! executable-class
com.espirit.moddev.uxbridge.inline.UxbResultHandler

Since the messages are processed asynchronously and can take different amounts of time depending on the adapter and number of messages, it is possible to use a script parameter (messageTimeout) to specify the maximum amount of time (in seconds) that the service should wait for the response message before the processing times are evaluated.

INFO 25.07.2012 10:38:44.811 Time for #uxb/pressreleasedetails/UXB/DE/704 (mongodb): 220ms
INFO 25.07.2012 10:38:44.812 Time for #uxb/pressreleasedetails/UXB/EN/704 (mongodb): 173ms
INFO 25.07.2012 10:38:44.813 48/48 deployed successfully (overall: 210ms, monogodb: 183ms, postgres: 238ms).
INFO 25.07.2012 10:38:44:813 finished task ‘GetTimings’ – schedule entry ‘UX-Bridge (News)’ (id=6191)

The results of the messages that were not processed until after the specified waiting period are kept in the memory. The length of time set until these are automatically deleted can be configured in the service settings.

As an alternative to the messageTimeout parameter, a heartbeat can be configured. Therefore, the script parameter enableHeartbeat has to be set to true. The default value for the highest accepted amount of time in milliseconds between two heartbeat messages is 15000. With the script parameter heartbeatTimeout, a different timeout threshold can be configured in milliseconds. If the ResultHandler doesn’t receive a heartbeat message for longer than the configured amount of time, the schedule is considered failed and a timeout message is displayed.

INFO  06.07.2016 10:52:40.293 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Set heartbeat timeout to 10
INFO  06.07.2016 10:52:40.293 (com.espirit.moddev.uxbridge.service.UxbServiceStatisticsResponseHandler): Time since last heartbeat is 15, timed out
ERROR 06.07.2016 10:52:40.293 (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Timeout

For instructions on how to back up and restore FirstSpirit projects, refer to the FirstSpirit Documentation for Administrators.

Usually there are very few messages on the message broker. A message in the queue leaves the queue as soon as it is retrieved. The message broker passes responsibility for subsequent handling of the message to the adapter. Messages that still have not been "picked up" by the adapter are on the broker. If you want to back these up, this can be accomplished by backing up the KahaDB if the messages and the KahaDB are permanently saved.

For details on this, refer to Section Backing up the message store.

The procedure for backing up the data in a content repository depends on the solution employed. Depending on the system used, follow the instructions from the corresponding documentation to create a backup.

If data recovery of the FirstSpirit server is required due to a failure, please contact e-Spirit AG Technical Support to receive relevant instructions.

If the error occurs in the UX-Bus infrastructure and the infrastructure has been damaged, backed-up data does not have to be manually restored in most cases. In the worst case, the messages that were not yet processed on the UX-Bus and were not persistently stored are lost. In the default configuration, however, persistence is enabled.

With the Apache ActiveMQ, the KahaDB is used to save and process messages. Therefore, the KahaDB will have to be restored if data is lost. This in turn is only possible if the broker is configured so that the KahaDB is persistently stored. Otherwise any data on the UX-Bus at the time of the crash will be lost. Normally the Apache ActiveMQ itself takes care of restoring persistently stored data when restarting the application. For custom configurations, for example in conjunction with a relational database or the KahaDB on a shared file system, the backup mechanisms common for the respective technology can be used. In addition, high availability is explained in Section High availability.

No substantial problems should arise if the adapter has crashed, since data loss is to be anticipated only in extreme situations. Normally the messages simply remain on the broker until the adapter is restarted and retrieves these messages.

Most likely, only the message that was being processed at the time of the crash will be lost, depending on the implementation of the adapter. In this case, you can carry out a redeployment of the data in FirstSpirit.

If data has to be restored in the external repository, whatever steps are necessary have to be carried out there. These vary depending on the application used. You can look up the details in the respective documentation. A typical use case could be restoring a relational database backup.

Errors in the UX-Bridge task in the schedule

INFO  18.07.2012 12:29:31.180 {seID=6191} (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): starting task 'UX-Bridge – Activate Generation' - schedule entry 'UX-Bridge (News)' (id=6191)

ERROR 18.07.2012 12:29:31.185 {seID=6191} (de.espirit.firstspirit.server.scheduler.ScriptTaskExecutor): error during script execution : de.espirit.firstspirit.access.ServiceNotFoundException: Service com.espirit.moddev.uxbridge.api.v1.service.UxbService' not found
de.espirit.firstspirit.access.ServiceNotFoundException: Service com.espirit.moddev.uxbridge.api.v1.service.UxbService' not found

Errors in the UX-Bridge generation schedule

INFO  18.07.2012 12:40:45.943 {seID=6191} (com.espirit.moddev.uxbridge.service.UxbServiceImpl): UXB Service: calling Producer

ERROR 18.07.2012 12:40:51.098 {seID=6191} (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Could not connect to broker!

Warnings occur in the UX-Bridge statistics report task

INFO  18.07.2012 12:47:14.694 {seID=6191} (de.espirit.firstspirit.server.scheduler.ScheduleManagerImpl): starting task 'UX-Bridge Statistics Report' - schedule entry 'UX-Bridge (News)' (id=6191)

WARN  18.07.2012 12:47:14.736 {seID=6191} (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Deployment for target expired: #uxb/pressreleasesdetails/UXB/EN/256 (postgres)

INFO  18.07.2012 12:47:14.736 {seID=6191} (com.espirit.moddev.uxbridge.service.UxbServiceImpl): Time for #uxb/pressreleasesdetails/UXB/EN/704 (mongodb): 580ms

The UX-Bus does not log any information regarding routing messages in the default configuration.

In Section Logging you can find information on how to configure logging accordingly.

It is possible that the adapter cannot process the messages correctly. The developer of the adapter should write corresponding log outputs during its implementation so that these types of problems can be detected during ongoing operation.

Depending on the content repository being used, its log files and administration tools that may be available can aid in troubleshooting. We cannot provide additional information here, since these components are selected for a specific project.

FirstSpirit server reports that a JMS connection to the UX-Bus could not be established

WARN  17.07.2012 16:30:46.483 (org.apache.camel.component.jms.DefaultJmsMessageListenerContainer): Setup of JMS message listener invoker failed for destination 'FS_IN' - trying to recover. Cause: java.io.EOFException

WARN  17.07.2012 16:30:46.486 (org.apache.camel.component.jms.DefaultJmsMessageListenerContainer): Setup of JMS message listener invoker failed for destination Adapter-Statistics-Response-Route' - trying to recover. Cause: java.io.EOFException

WARN  17.07.2012 16:30:46.488 (org.apache.camel.component.jms.DefaultJmsMessageListenerContainer): Could not refresh JMS Connection for destination 'ROUTEIN' - retrying in 5000 ms. Cause: Could not connect to broker URL: tcp://localhost:61616. Reason: java.net.ConnectException: Connection refused

WARN  17.07.2012 16:30:46.489 (org.apache.camel.component.jms.DefaultJmsMessageListenerContainer): Could not refresh JMS Connection for destination Adapter-Statistics-Response-Route' - retrying in 5000 ms. Cause: Could not connect to broker URL: tcp://localhost:61616. Reason: java.net.ConnectException: Connection refused

WARN  17.07.2012 16:30:46.489 (org.apache.activemq.transport.failover.FailoverTransport): Transport (tcp://127.0.0.1:61616) failed, reason:  java.io.EOFException, attempting to automatically reconnect

ERROR 17.07.2012 16:30:51.666 (org.apache.activemq.transport.failover.FailoverTransport): Failed to connect to [tcp://localhost:61616] after: 10 attempt(s)

False positives in UX-Bridge statistics report task

ERROR Tue Jul 24 14:37:30 CEST 2012 (de.espirit.firstspirit.client.AbstractGuiHost) ExceptionHandler.uncaughtException() - java.lang.SecurityException: Unable to create temporary file
java.lang.SecurityException: Unable to create temporary file
java.lang.SecurityException: Unable to create temporary file
    at java.io.File.checkAndCreate(null:-1)
    at java.io.File.createTempFile0(null:-1)
    at java.io.File.access$100(null:-1)
    at java.io.File$1.createTempFile(null:-1)
    at sun.misc.IOUtils.createTempFile(null:-1)
    at javax.imageio.stream.FileCacheImageInputStream.<init>(null:-1)
    at com.sun.imageio.spi.InputStreamImageInputStreamSpi.createInputStreamInstance(null:-1)
    at javax.imageio.ImageIO.createImageInputStream(null:-1)
    at javax.imageio.ImageIO.read(null:-1)
    at de.javasoft.plaf.synthetica.painter.ImagePainter.<init>(ImagePainter.java:234)
    at de.javasoft.plaf.synthetica.painter.ScrollBarPainter.paintScrollBarThumbBackground(ScrollBarPainter.java:175)
    at de.javasoft.plaf.synthetica.painter.SyntheticaPainter.paintScrollBarThumbBackground(SyntheticaPainter.java:569)
    at javax.swing.plaf.synth.ParsedSynthStyle$DelegatingPainter.paintScrollBarThumbBackground(null:-1)
…
Trace message truncated for length over 10K

If not already present, one should add a queue named QMA, using the MQ Explorer. We use port number 1414, for all other settings we use: Default.

Figure 10. MQ Explorer Queue Manager

If not already present, one should add a listener named QMA.LISTENER and port 1414 for the queue manager QMA.

Figure 11. MQ Explorer Listener

For the configuration we will use the Publisher/Subscriber-Principle recommended since IBM Websphere MQ 7. Here, themes are used as publisher. Any subscriber can subscribe to a topic using the queue manager. Beneath the queue manager QMA two local queues FS_IN and BUS_OUT are added.

Figure 12. MQ Explorer queue manager

Afterwards two topics are created that are used to publish messages from FirstSpirit (FS_OUT) and to push messages from the live-system (BUS_IN) to the bus.

Figure 13. MQ Explorer Themes

We will add two subscriptions next:

Figure 14. MQ Explorer Subscriptions

Beneath the queue manager QMA and Channels a new server-connection-channel named SRVCONN (Settings: Default) was added.

Figure 15. MQ Explorer Channels

If all users are locked out beneath Channel Authentication Records, this lock must be removed.

The module uxbridge-module-x.x.x.fsm should be installed according to manual and All Rights should be checked.

To use the UX-Bridge in connection with IBM Websphere MQ, it is necessary to copy the files jms.jar and com.ibm.mq.allclient.jar to the folder FS_ROOT → shared → lib of the FirstSpirit server. The files are part of the Websphere MQ classes for Java and can be downloaded for your Websphere-Version from IBM Fix Central (https://www.ibm.com/support/fixcentral/).

To configure the UX-Bridge Service one has to replace the following place holders:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jms="http://www.springframework.org/schema/jms" xsi:schemaLocation="http://www.springframework.org/schema/beans        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd        http://camel.apache.org/schema/spring        http://camel.apache.org/schema/spring/camel-spring.xsd http://www.springframework.org/schema/jms http://www.springframework.org/schema/jms/spring-jms-3.0.xsd">
  <bean id="webphere-mq-topic" class="org.apache.camel.component.jms.JmsComponent">
    <property name="connectionFactory" ref="websphere-mq-usercredentials-connection-proxy-topic"/>
  </bean>

 <bean id="webphere-mq" class="org.apache.camel.component.jms.JmsComponent">
    <property name="connectionFactory" ref="websphere-mq-usercredentials-connection-proxy"/>
  </bean>

<bean id="websphere-mq-connection-topic" class="com.ibm.mq.jms.MQTopicConnectionFactory">
                     <property name="transportType" value="1"/>
                    <property name="hostName" value="<hostname>"/>
                    <property name="port" value="1414"/>
                    <property name="queueManager" value="QMA"/>
<property name="channel" value="SRVCONN"/>
  </bean>

<bean id="websphere-mq-connection" class="com.ibm.mq.jms.MQConnectionFactory">
                     <property name="transportType" value="1"/>
                    <property name="hostName" value="<hostname>"/>
                    <property name="port" value="1414"/>
                    <property name="queueManager" value="QMA"/>
<property name="channel" value="SRVCONN"/>
  </bean>

<bean id="websphere-mq-usercredentials-connection-proxy-topic" class="org.springframework.jms.connection.UserCredentialsConnectionFactoryAdapter">
   <property name="targetConnectionFactory" ref="websphere-mq-connection-topic"/>
   <property name="username" value="<username>"/>
   <property name="password" value="<password>"/>
 </bean>

<bean id="websphere-mq-usercredentials-connection-proxy" class="org.springframework.jms.connection.UserCredentialsConnectionFactoryAdapter">
   <property name="targetConnectionFactory" ref="websphere-mq-connection"/>
   <property name="username" value="<username>"/>
   <property name="password" value="<password>"/>
 </bean>

  <camelContext xmlns="http://camel.apache.org/schema/spring" id="camelContext" trace="false">
    <package>com.espirit.moddev.uxbridge.service</package>
    <template id="producerTemplate" />
    <endpoint id="FS-Out" uri="webphere-mq-topic:topic:FS.BUS_IN" />
    <onException>
      <exception>java.lang.Exception</exception>
      <handled>
        <constant>true</constant>
      </handled>
      <process ref="uxbExceptionProcessor" />
    </onException>
    <route id="Adapter-Statistics-Response-Route">
      <from uri="webphere-mq:queue:FS_IN" />
      <convertBodyTo type="com.espirit.moddev.uxbridge.api.v1.service.UXBEntity" />
      <bean ref="UxbServiceStatisticsResponseHandler" method="print" />
    </route>
  </camelContext>
  <bean id="UxbServiceStatisticsResponseHandler" class="com.espirit.moddev.uxbridge.service.UxbServiceStatisticsResponseHandler">
    <constructor-arg ref="camelContext" />
  </bean>
  <bean id="uxbExceptionProcessor" class="com.espirit.moddev.uxbridge.inline.UxbExceptionProcessor" />
</beans>

The best advice is to install a parallel UX-Bus. This is similar to the installation which has already been done. When the new installation is ready, it would be wise to copy the configuration from the old installation to the new installation.

After that the old version of the UX-Bus can be stopped and the new version can be started. If there is a Windows or a Unix Service, this service must be configured with the new version of the UX-Bus. Details can be found here: http://activemq.apache.org/run-broker.html.

At first the module must be updated. This is equal to the approach in chapter Update the UX-Bridge module.

After the reboot the web application must be refreshed. Therefor it necessitates a click on the Update uses button at the UX-Bus module in the ServerManager.

Figure 16. Update uses

At the next dialog a click on the Update button starts the update process.

Figure 17. Update