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.
Create and populate the underlying database.
Decide on a service name.
Ensure you are licensed to run the Xmarc Java services.
Configure a Service Agent which will ultimately launch the service.
Choose a port for the service to listen for client connections.
Create a property file containing the runtime environment for the service.
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.
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.
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.
An installation must have an fxengine license from Xmarc to run a messaging service.
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 agentx.classpath=<install_dir>/cmt # Location of engine support classes agentx.classpath=<install_dir>/cmt/xcore.jar # Location of Oracle jdbc classes (provided by Oracle) agentx.classpath=<oracle_dir>/jdbc/lib/classes12.zip
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).
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.
Every Xmarc Java service must have a property file providing the runtime environment details and a messaging service is no exception. Its environment comprises:
a service title, to differentiate the service from other messaging services
a host name, to which switchboard users can connect
a host port (open to the internet), to which switchboard users can connect
database connection details, for the service to connect to the underlying messaging database
Other entries in the property file are as standard for all Xmarc Java services.
An example property file is as follows:
engine.service=XCMT engine.class=XRedLine # 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 switchboard.host=myhost.mydomain.com # The switchboard port number on which clients can log in # If necessary a hole in the firewall must be provided for external access switchboard.port=7432 # JDBC connection information db.url=jdbc:oracle:thin:@dbhost:1521:oracl db.user=redline db.password=redline # Debugging logger.logging=yes
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.
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:
http://<myhost>/xmarc/Broker?service=XCMT&cmd=summary
Robert is now your uncle
.