Just a second...

Running from within a Java application

To run Diffusion™ from within a Java™ application instantiate, configure and start a DiffusionServer object.

Creating a server

DiffusionServer is available in the com.pushtechnology.diffusion.api.server. You can instantiate it with one of the following constructors:

Default configuration
DiffusionServer server = new DiffusionServer();
This instantiates the server with default configuration options. The default configuration is read from the XML configuration files in the etc directory of your Diffusion installation. Required aspects of the server must be configured before it is started. These can be configured programmatically. For more information, see Programmatic configuration.
Bootstrap properties
DiffusionServer server = new DiffusionServer(bootstrapProperties);
This specifies a set of properties inside a Properties object. The following properties are supported:
Property Description Default
diffusion.home The base installation directory Calculated from the location of the diffusion.jar file.
diffusion.config.dir The configuration directory, where the XML configuration files are located. Relative paths are resolved from diffusion.home. diffusion.home/etc
diffusion.ext.dir The ext directory, where application-supplied libraries are located. Relative paths are resolved from diffusion.home. diffusion.home/ext
diffusion.license.file The license file diffusion.config.dir/license.lic
diffusion.keystore.file The keystore file required to decrypt the license diffusion.config.dir/licence.keystore

These properties can also be set as system properties.

Whichever approach to instantiation that you use, a full set of XML configuration files can be present in the configuration directory and tuned as required or just a partial set of the files can be present and all missing configuration supplied programmatically.

Configuring the Diffusion server

Once the server object has been instantiated some properties can be configured. The root configuration object can be obtained from the server object as follows:

ServerConfig config = server.getConfig();

Alternatively the root can be obtained using ConfigManager.getServerConfig().

The configuration is populated from the XML configuration files in the installation or in the configuration directory specified by diffusion.config.dir. You can further customize the configuration to fit your requirements. For an example, see the following sample code:
DiffusionServer server = new DiffusionServer();

ServerConfig config = server.getConfig();


// Connector ConnectorConfig connector = config.addConnector("Client Connector");
// Configure connector as required....

// Thread Pools
ThreadsConfig threads = config.getThreads();
ThreadPoolConfig inbound = threads.addPool("Inbound");
inbound.setCoreSize(3);
inbound.setMaximumSize(10);
inbound.setQueueSize(2000);
threads.setInboundPool(inbound.getName());
threads.setBackgroundPoolSize(2);

// Queues QueuesConfig queues = config.getQueues();
QueueConfig queue = queues.addQueue("DefaultQueue");
queue.setMaximumDepth(10000);
queues.setDefaultQueue("DefaultQueue");

// Multiplexer MultiplexerConfig multiplexer = config.addMultiplexer("Multiplexer");
multiplexer.setSize(4); 
Note: The logging configuration cannot be changed using the ServerConfig object. By the time the configuration objects are available to your Java application, the logging properties are locked. The LoggingConfig object is read-only.

Monitoring the Diffusion server lifecycle

The DiffusionServer class provides methods to add and remove a lifecycle listener on the server instance.

addLifecycleListener(LifecycleListener stateCallback);
removeLifecycleListener(LifecycleListener stateCallback);
The lifecycle listener is a callback that is called whenever the server state changes. The Diffusion server can have the following states:
INITIAL
An instance of the DiffusionServer exists, but has not been started.
STARTING
The server is starting.
STARTED
The server has started.
STOPPING
The server is stopping.
STOPPED
The server has stopped.

Starting the server

After the server configuration has been completed, the server can be started using server.start().

Connectors start to listen on the configured ports.

Stopping the server

The server can be stopped using server.stop() at which point the server is no longer available.

Run requirements

A simple way to use Diffusion as a library within your application is to install Diffusion and include the path to diffusion.jar in your CLASSPATH.

If you want to repackage the Diffusion code more extensively, be aware of the following concerns:
  • diffusion.jar depends on other library files in the installation's lib directory and are referenced in the jar's manifest Class-Path entry. You must also make the code in these libraries available.
  • You still require a Diffusion installation. The installation provides the configuration, licence, and log directories. The installation directory is calculated from the location of diffusion.jar. If diffusion.jar is not loaded from a URL classloader, or has been moved from the product installation, use the bootstrap properties constructor and set the diffusion.home system property to the installation directory.

Limitations

Currently only one Diffusion server can be instantiated in a Java VM and it can be started only once.