Configuration
http://plover.sourceforge.net \| Last published: 03 April, 2005

Executive Summary

Home

Overview

License

Download

Project Summary

Change Notes

Using Plover

Installation

Configuration

Hosted Entities

Client-side Invocation

Network Discovery

API Documentation

This project is hosted on

Introduction

In this document we shall explain how to configure the Plover server-side hosting environment. Henceforth in this document, unless explicitly mentioned, the name Plover is synonymous with the server-side entity hosting environment.

Plover supports two mechanisms of host configuration: programatically setting all parameters and reading entries from a XML file to set all parameters in one operation. You can use both these mechanisms in tandem, before you start the hosting environment. For example, you can configure the hosting environment using a base set of values using a configuration file and then fine-tune the same using the API methods.

An Example Configuration

The interface omd.plover.hosting.spi.IHostConfig provides all methods to configure the entity hosting environment. An example code is as provided below:




import omd.plover.hosting.launcher.app.PloverLauncher;

import omd.plover.hosting.spi.IHostConfig;



...

PloverLauncher pl = new PloverLauncher();

IHostConfig config = pl.getConfig();

config.setRMIEnabled(true);

config.bindEntityObject("userMgr", "sample.UserManager");

config.bindEntityScript("perMgr", "sample/PermissionManager.script");

...



pl.start();

The same configuration effect as the code example above can be achieved using information stored in a XML file. The corresponding XML data is as provided below:

<?xml version="1.0"?>

<plover-host>
  <rmi-server />
  <object-entity id="userMgr" type="sample.UserManager" />
  <script-entity id="perMgr" path="sample/PermissionManager.script" />
</plover-host>

The structure of the XML configuration is the same irrespective of Plover being installed as a generic service or within a servlet container. The example code below configures Plover with the contents of the XML file, it being assumed that the name of the file is plover-host.xml.




import omd.plover.hosting.launcher.app.PloverLauncher;



...

PloverLauncher pl = new PloverLauncher();

pl.getConfigure("plover-host.xml");

...



pl.start();

XML Configuration Structure

The complete DTD for the Plover XML configuration file is available here. Portions of the same are explained in details below. For details on the corresponding APIs for configuration, refer to the javadoc documentation of the omd.plover.hosting.spi.IHostConfig interface.

<!ATTLIST plover-host
  type NMTOKEN #IMPLIED
  version NMTOKEN #IMPLIED
>

These parameters defines the specific type and version of service being provided by one server-side hosting instance. This information is used to perform filtering of available services, in case more than one host instance is detected during network discovery.

<!ELEMENT rmi-server EMPTY>
<!ATTLIST rmi-server
  port NMTOKEN #IMPLIED
  bindPath NMTOKEN #IMPLIED
  leaseValue NMTOKEN #IMPLIED
>

<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
  address NMTOKEN #IMPLIED
  port NMTOKEN #IMPLIED
>

The RMI transport and the network discovery service needs to have explicit entries in the configuration XML to be activated with Plover startup. In the absence of attribute values for these XML elements, the corresponding services are started with predefined values.

<!ELEMENT session EMPTY>
<!ATTLIST session
  timeout NMTOKEN #REQUIRED
>

The Plover invoker does not maintain a persistent TCP connection with the server-side entity host. Client sessions therefore needs to be maintained on the server using similar concepts as HTTP. Authetication information between the client and the server is transferred only once, each time a session is established.

Use this element to set an explicit session timeout value in milliseconds. If not provided, the timeout value defaults to 30 seconds.

<!ELEMENT access-controller (init-param*)>
<!ATTLIST access-controller
  type NMTOKEN #REQUIRED
>

A Plover access controller is used to perform client authetication and per-method access control based on the credentials provided during authentication. The type attribute should provide the fully qualified class name of the custom access controller implementation. Further customizations at runtime are provided by information contained in the nested init-param elements.

In the absence of this configuration information, a default access controller is used by Plover that allows all client credentials to connect to and access all methods on all hosted entities.

<!ELEMENT global-object (init-param*)>
<!ATTLIST global-object
  id NMTOKEN #REQUIRED
  type NMTOKEN #REQUIRED
>

Global objects have a lifespan that equals that of the Plover hosting environment. They are initialized at startup and are independent of any client session. Global objects serve to provide common infrastructure to hosted entities (e.g. a datasource, an EJB locator, etc.)

Global objects are referred by the id attribute from within hosted entities. The type attribute should provide the fully qualified name of the global object class. Further customizations at runtime are provided by information contained in the nested init-param elements.

<!ELEMENT object-entity EMPTY>
<!ATTLIST object-entity
  id NMTOKEN #REQUIRED
  type NMTOKEN #REQUIRED
  sticky (true | false) #IMPLIED
>

<!ELEMENT script-entity EMPTY>
<!ATTLIST script-entity
  id NMTOKEN #REQUIRED
  path NMTOKEN #REQUIRED
  sticky (true | false) #IMPLIED
>

These elements pertain to actually binding a hosted entity with Plover. The id attribute defines the Plover path against which the entity is bound. This path information is used to resolve method invocations between the invoker and the host.

For hosted entities that are implemented as Java classes, the type attribute should contain the fully qualified name of the class. For hosted entities that are implemented as Javascript fragments, the path attribute should contain the path to the corresponding script file.

The sticky attribute determines the lifecycle of a hosted entity. By default, this attribute is false indicating that hosted entities are created and destroyed with every remote invocation. A true for this attribute signifies that the same hosted entity instance is reused across remote invocations for the same client session.

Default Configuration Values

In the absence of any additional parameters for RMI transport, the bind path defaults to plover and the registry port value to 1099. The RMI lease value defaults to 30 seconds.

In the absence of any additional parameters for discovery service, the multicast address defaults to 239.255.255.255 and the corresponding port defaults to 6789.