Xmarc Collaborative Messaging - Service Setup

A server-side messaging service is a Java service, launched by the Xmarc Service Manager, to which clients connect via the Service Broker.

Assuming you have an Enterprise Spatial installation (6.1 or later), you should perform the following steps to set up such a service.

  1. Create and populate the underlying database.

  2. Decide on a service name.

  3. Ensure you are licensed to run the Xmarc Java services.

  4. Configure a Service Agent which will ultimately launch the service.

  5. Choose a port for the service to listen for client connections.

  6. Create a property file containing the runtime environment for the service.

  7. Launch (start) the service via the Service Manager.

It is assumed that you the reader are familiar with the Xmarc Service Manager/Broker/Agent middle-tier architecture.

We have indicated in red parameters and values which typically will need configuring.

Create and populate the database

SQL scripts are provided (in <install_dir>/cmt) to create and populate an Oracle database.

The scripts and the schema for such a database are described here.

There must be a database before a messaging service can be launched.

Decide on a service name

The service name is that by which the user will connect to the service, e.g. XCMT

When connecting via the API this is done via the XmConnect API method, for example a service name of XCMT would have a connection URL of http://<myhost>/xmarc/Broker?service=XCMT, where <myhost> is your machine hosting the Service Manager and Broker.

Conventially we use upper-case characters for service names.

Required licensing

An installation must have an fxengine license from Xmarc to run a messaging service.

Configure a service agent

Java services are launched via a Service Agent, which may or may not be running on the same host as the Service Manager and Broker.

For an agent to launch a messaging service correctly it must have a classpath correctly set for it to find the following required Java classes and class archives:

XRedLine.class - the main messaging Java class

xcore.jar - the associated support classes required by XRedLine

classes12.zip (or .jar) - the required Oracle classes required by JDBC

Therefore the relevant directories/files should be set in the agent property file, e.g.

# Location of XRedLine.class
# Location of engine support classes
# Location of Oracle jdbc classes (provided by Oracle)

The first 2 files are provided in <install_dir>/cmt but may be moved if necessary.

You should now start (or restart) the agent and check that everything is hunky dory via the Service Manager (button Agent Admin). You may have to add the agent if it is not already known to the Service Manager (button Agent Admin then Add/Change).

Choose a switchboard port

The service will listen for clients to connect (i.e. to log in) on a nominated port. You can nominate any port not currently in use by another application. For no specific reason we usually use port 7432.

If the service is to communicate with users beyond a corporate firewall, a hole must be punched in the firewall to allow them to connect. Your network administrator will be able to arrange such a hole.

Configure a service property file

Every Xmarc Java service must have a property file providing the runtime environment details and a messaging service is no exception. Its environment comprises:

Other entries in the property file are as standard for all Xmarc Java services.

An example property file is as follows:

# This property is obligatory
# A title to  distinguish the service from other redlining services
service.title=CMT Development
# These 2 properties are obligatory
# The switchboard host name on which clients can log in
# The switchboard port number on which clients can log in
# If necessary a hole in the firewall must be provided for external access
# JDBC connection information
# Debugging

and is included in the distribution (in <install_dir>/cmt) as xredline.properties. This should be copied and edited to a directory where the Service Agent has access to it.

Start the service

Assuming the Service Agent which will launch the service has been started and has is known to the Service Manager, log in to the Xmarc Service Manager (via a browser) on the machine which is to host the service, e.g. http://<myhost>/xmarc/SvcMgr.

On the New Service page, select the agent which will launch the service, add the relevant fields to start the service and click Submit, e.g.

Service Name: XCMT (the logical name for the service)

Service Command: XRedLine (the java class of the service)

Service Start Parameters: c:/wherever/xredline.properties (the name and location of the service property file)

The servce should now be up and running. Use the Report button to make sure.

You can also check a client connection to the service by hitting the following url from a browser, which should display a status page of users, groups and sessions:


Robert is now your uncle