Getting Started with Joram

The minimum to get and launch a Joram server from scratch.

Pre-Installation Requirements

Hardware:

• 20Mb of free disk space for the binary distribution.
• 11Mb of free disk space for the source distribution.

Operating Systems:

Joram will run on any platform that supports Java runtime environment (compliance with Java 8, 11 and 17), in particular:

• Windows 7 to 11.
• Ubuntu Linux, CentOS Linux, Debian Linux.

Installation of a binary distribution

Installing Joram is simple:

• Obtain the latest Joram release from Download page: joram-release-5.x.y.zip.
• Expand the files into a directory:
  • using unzip for unix users:
    unzip joram-release-5.x.y.zip,
  • using 7-Zip utility for Windows users.

Joram is now ready to work.

Running a server using the scripts

You can launch a Joram server using the commands provided with Joram::

• Fix environment variables:
  • Set JAVA_HOME to the directory where JDK is installed.
  • Set JORAM_HOME to the directory that you installed Joram.
• Change directory to JORAM_HOME.
• Change directory to the samples/bin directory.
• Execute either the single_server.sh (linux) or single_server.bat (windows).

Congratulations, you are running the default configuration!

Stopping the Joram server

Simply hit ^C, Joram is based on top of an atomic engine so you can violently stop it without damage.

You can also stop it using a JMX console or the administration API.

Running a sample using ant

Once you have downloaded and installed Joram (see above), you can try to run one of the multiples examples provided in the distribution. The sources of these examples are located under the samples/src/joram directory.

You need Ant 1.6.5 or greater in order to run this tutorial.

Building the samples

go to the samples/src/joram directory. First compile all the samples, simply typing:

• ant clean compile
• It creates a samples/classes/joram directory holding the compiled classes.
• For removing it, type ant clean.

Running the classic sample

For example to launch the classic example (see also tutorial).

• Launch the Joram server:
  • ant reset single_server
  • The server is launched in the samples/run created directory.
    The reset ant target can be used to remove all out-of-date data.
  • Be careful, this command doesn't return while the server is running.
• Run the administration code, creating ConnectionFactory, Topic and Queue objects:
  • ant classic_admin
  • Each administered objects is bind in JNDI, and you may use a JMX console to observe the configuration.
• Then run the messages producers and consumers. There is several scenarios depending of the messaging domain used; using the point-to-point messaging:
  • ant sender: sends 10 messages to the defined queue,
  • ant browser: allows to look messages on queue, then
  • ant receiver: consumes 10 messages from the queue.
• Now you can stop the Joram server, typing a ^C in the corresponding window.

Other samples

Simple demonstrations

There is many examples in the sample directory:

• the chat sample provides a simple implementation of a chat,
• the distributed sample demonstrates the use of multiples servers,
• And the dotcom demonstration simulates what could be a commercial transaction involving many participants.

Specialized destinations

Other samples demonstrates the use of particular functionalities of Joram:

• Dead message queues,
• Hierarchical topics,
• clustered queues and topics (see tutorial),
• FtpQueue and mail destinations,
• Scheduler queues,
• Monitoring topics and topics (see tutorial),
• Collector queues and topics,
• JMS Bridge destinations (see tutorial).

Enhanced behavior

Last samples demonstrates particular functionalities of Joram:

• JCA Connector,
• JAAS enhancements,
• High-Availability,
• Soap connectivity, etc.

For more informations about these samples, see the Joram Documentation.

Building Joram from of a source distribution

Building Joram is simple:

• Obtain the latest Joram source distribution from Download page: joram-release-5.x.y-src.zip.
• Expand the files into a directory:
  • using unzip for unix users:
    unzip joram-release-5.x.y-src.zip,
  • using 7-Zip utility for Windows users.
• Change to joram-5.x.y created directory.
• Launch maven through mvn install command.

Joram is now ready to work.

Checking out from SVN and building

Make sure you have SVN (subversion) installed; if not download it from the subversion site:

• svn checkout svn://svn.forge.objectweb.org/svnroot/joram/trunk/joram
• Change to joram created directory.
• Launch maven through mvn install command.

Joram is now ready to work.

Additionnals informations about svn are available here.