oc.cmi-doc.2.0.10.source-code.userguide.xml Maven / Gradle / Ivy
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
<bookinfo>
<title>CMI User Guide</title>
<authorgroup>
<author>
<surname>Bouzonnet</surname>
<firstname>Loris</firstname>
</author>
<corpauthor>JOnAS Team</corpauthor>
</authorgroup>
<copyright>
<year>2007,2008</year>
<holder>OW2 Consortium</holder>
</copyright>
<abstract>
<para>The CMI user guide is intended for developers wanting to develop
clustered applications.</para>
</abstract>
<date>March 2008</date>
<productname>CMI</productname>
<productnumber>2.0.0</productnumber>
<mediaobject>
<imageobject>
<imagedata fileref="images/logo-cmi.png" />
</imageobject>
</mediaobject>
<pubdate>$Id: userguide.xml 2131 2008-10-06 14:35:30Z pelletib $</pubdate>
</bookinfo>
<glossary>
<glossdiv>
<title>Vocabulary</title>
<para>This glossary defines the vocabulary used by this user guide. A
definition of common terms can be found on <ulink
url="http://java.sun.com/docs/glossary.html">the glossary provided by
<trademark>Sun</trademark></ulink>.</para>
<glossentry>
<glossterm id="gloss_clustered_obj">Clustered object</glossterm>
<glossdef>
<para>Remote object that has clustering informations.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_remote_obj">Remote object (or RMI
object)</glossterm>
<glossdef>
<para>Object having methods that can be invoked remotely with a RMI
connection.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_clustering_info">Clustering
information</glossterm>
<glossdef>
<para>Information that allows to perform invocations on an object
while keeping a distributed load. The policy and the strategy are
some clustering informations. Clustering informations are a part of
the cluster view.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_manager">Manager of the cluster view</glossterm>
<glossdef>
<para>A manager handles replicated data to model the cluster view.
There are two kinds of manager: one for clients and one for servers.
The one for clients can only read the cluster view, while the one
for servers can modify it. The cluster view manager is a singleton
in a JVM.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_replicated_data">Replicated data</glossterm>
<glossdef>
<para>Raw data copied on each JVM belonging to the cluster.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_jvm">JVM</glossterm>
<glossdef>
<para>An instance of the Java Virtual Machine that contains one and
only one manager of the cluster view.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_cluster_view">Cluster view</glossterm>
<glossdef>
<para>View on a cluster state shared by the managers. Two kinds of
view exist: client view and server view.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_policy">Policy of load-balancing</glossterm>
<glossdef>
<para>Algorithm for choosing one server among a list. Policy and
strategy form the algorithm of load-balancing.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss_strategy">Strategy of load-balancing</glossterm>
<glossdef>
<para>Algorithm for choosing a list of server among an other one. A
strategy is applied before a policy in order to modify its
behaviour.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Service flow</glossterm>
<glossdef>
<para>It corresponds to the requests initiated by the clients (e.g.
accesses to registry, EJB requests).</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Control flow</glossterm>
<glossdef>
<para>It corresponds to the cluster logic requests (e.g. update
servers list, get servers load,...).</para>
</glossdef>
</glossentry>
</glossdiv>
</glossary>
<chapter>
<title>Introduction</title>
<para>This chapter gives the rationale of CMI and provides a few
information about its internals.</para>
<section>
<title>Motivations for clustering objects</title>
<para>When too many clients perform method invocations on a single
remote object, we can expect a fall of quality of service. In addition,
if this object is no more accessible, none of the clients will be
satisfied.</para>
<para>So clustering objects can contribute to obtain two good
properties:</para>
<orderedlist>
<listitem>
<para><emphasis>scalability</emphasis>, i.e. increase the
application capacity in terms of number of clients and response
time.</para>
<para>Load-balancing is a mechanism avoiding overload of
server.</para>
</listitem>
<listitem>
<para><emphasis>fault tolerance and continuity of
service</emphasis>, i.e. provide high-availability of
service.</para>
<para>Failover is a mechanism avoiding interruption of
service.</para>
</listitem>
</orderedlist>
<para>No specification (no standard) describes how to get them: it is
the purpose of CMI.</para>
</section>
<section>
<title>Provided solution</title>
<para>CMI is a framework that provides a generic system to define and
configure clusters of RMI objects. CMI allows to dissociate objects from
registries and servers by defining global registries and clusters of
objects. By this way, it can ensure a scalability and high-availability
of accesses to clustered (or not, <link linkend="lbregistries">see
below</link>) objects.</para>
<para>Its main features are:</para>
<itemizedlist>
<listitem>
<para>Support of all types of remote objects</para>
<para>CMI doesn't expect any specific types of object, but because
it uses JNDI to access them, the type is fixed by the application on
the server-side that binds objects into the registry.</para>
</listitem>
<listitem>
<para>Definition of load-balancing algorithms with POJOs</para>
<para>The load-balancing algorithm is split in two distinct parts to
achieve reusability: policies and strategies.</para>
</listitem>
<listitem>
<para>Dynamic policies and strategies of load-balancing</para>
<para>The load-balancing algorithm is defined before the deployment
and can evolve afterwards. New definitions of policies and
strategies are downloaded by clients. More, it is possible to add
properties to a policy in order to enhance still the
dynamicity.</para>
</listitem>
<listitem id="lbregistries">
<para>Capability to customize dynamically the algorithm of
load-balancing for the JNDI accesses</para>
<para>Non clustered objects can be also referenced by the global
registries to enjoy the smooth shutdown.</para>
</listitem>
<listitem>
<para>Smooth shutdown</para>
<para>Allow to disable creation of new connections on a server
waiting for shutdown.</para>
</listitem>
<listitem>
<para>Support of the load factor of servers in the algorithm of
load-balancing</para>
<para>Clients have up-to-date load factors.</para>
</listitem>
<listitem>
<para>Smart management of surrogates (stub or proxy)</para>
<para>To optimize the traffic network, surrogates are downloaded
lazily by clients and kept in a pool.</para>
</listitem>
<listitem>
<para>Separation of the service flow and the control flow</para>
<para>In each JVM, a single dedicated thread is in charge of the
control flow.</para>
</listitem>
<listitem>
<para>Multi-protocols support</para>
<para>CMI is fully independent of the communication protocol.</para>
</listitem>
<listitem>
<para>CMI is transparent for clients</para>
<para>CMI doesn't compel them to have many dependencies, by using
the smart factory.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="cmi.ug.lb">
<title>Load-balancing algorithm</title>
<section>
<title>An example of execution</title>
<para>The following figure shows how to define a weighted round-robin
in term of policy and strategy.</para>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/algoexample.png"
width="50%" scalefit="1"/>
</imageobject>
<caption><para>An use of the weighted round-robin</para></caption>
</mediaobject></para>
</section>
<section>
<title>General case</title>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/algomodel.png"
width="50%" scalefit="1"/>
</imageobject>
<caption><para>The chain strategy -> policy</para></caption>
</mediaobject></para>
</section>
</section>
<section xml:id="cmi.ug.arch">
<title>Architecture</title>
<para>This section is dedicated to make easier the use of CMI, by
providing informations on its conception. In a first time we will
distinguishes the interfaces of CMI, next we will give an overview of
the internal mechanisms of CMI.</para>
<section>
<title>Interfaces</title>
<para>CMI exposes three interfaces:</para>
<orderedlist>
<listitem>
<para>the API for users</para>
<para>It describes how to create and use clustered objects.</para>
</listitem>
<listitem>
<para>the API for integrators</para>
<para>It describes how to use CMI in an other project.</para>
</listitem>
<listitem>
<para>the SPI</para>
<para>It describes how to define its own implementations for
CMI.</para>
</listitem>
</orderedlist>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/interfaces.png"
width="30%" scalefit="1" format="PNG"/>
</imageobject>
<caption><para>The three interfaces exposed by
CMI</para></caption>
</mediaobject></para>
<para>This document will only focus on the API for users.</para>
<para>This is composed of the following elements:</para>
<itemizedlist>
<listitem>
<para>An implementation of context to intercept accesses to the
registries;</para>
</listitem>
<listitem>
<para>Annotations to define clustered objects;</para>
</listitem>
<listitem>
<para>Interfaces and utilities to define policies and
strategies;</para>
</listitem>
<listitem>
<para>A set of standard policies and strategies;</para>
</listitem>
<listitem>
<para>A MBean;</para>
</listitem>
<listitem>
<para>A smart-factory.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Internal mechanisms</title>
<para>Before describing the API for users in detail, this section
draws an overview of the internal mechanisms of CMI.</para>
<para>Its core can be divided in two parts:</para>
<orderedlist>
<listitem>
<para>A set of managers sharing the cluster view (no more one
manager by JVM);</para>
</listitem>
<listitem>
<para>A context and proxy intercepting calls on the wrapped
context and stub. They are associated with the manager of their
JVM.</para>
</listitem>
</orderedlist>
<section>
<title>Separation of the control and service flows</title>
<para>The interceptors separate the control and service flows, while
the managers handle the control flow.</para>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/sep_control_service.png"
width="40%" scalefit="1" format="PNG"/>
</imageobject>
<caption><para>Separation of the control and service flows at
lookup, bind and invoke times</para></caption>
</mediaobject></para>
<para><note>
<para>If the server application looks up (or invokes a method
of) a clustered object, it acts exactly as a client.</para>
</note></para>
</section>
<section>
<title>The interceptions</title>
<para>CMI provides interceptions of the calls performed by users.
They can occur at two moments:</para>
<orderedlist>
<listitem>
<para>Reading/writing into a registry with a context;</para>
<para>The context checks if the concerned object is clustered.
If it is, here is how the context proceeds:</para>
<itemizedlist>
<listitem>
<para>At a lookup:</para>
<para>Instead downloading a surrogate from the registry, the
context notifies its manager, generates a new proxy and
returns it.</para>
</listitem>
<listitem>
<para>At a bind (only for a server):</para>
<para>After binding the object in its local registry, the
context notifies its manager.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Invocation of methods on a clustered object with a proxy
returned by the context.</para>
</listitem>
</orderedlist>
<para>This proxy chooses a server using the policy and strategy of
the clustered object. For the chosen server, the proxy needs to get
the associated surrogate in order to perform the invocation. The
manager handles a pool of surrogates for each clustered
object.</para>
<para>The following figure illustrates the steps of an invocation,
when the surrogate is missing from the pool:</para>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/lazy_lookup.png"
width="40%" scalefit="1" format="PNG"/>
</imageobject>
<caption><para>Firstly, the proxy tries to get the surrogate for
a given clustered object and a given server.</para><para>Next,
because the pool doesn't contain the surrogate, it downloads
this by performing a lookup onto a
registry.</para><para>Finally, the surrogate is kept in the pool
and the proxy can invoke the method of the clustered
object.</para></caption>
</mediaobject>The lookup is performed just before the invocation
by the pool: this is a kind of lazy lookup.</para>
</section>
<section>
<title>The managers of the cluster view</title>
<para>The managers of the cluster view handle the control
flow.</para>
<para>There are two kinds of manager:</para>
<orderedlist>
<listitem>
<para>Server-side manager;</para>
<para>They share the whole cluster view and can modify
it.</para>
</listitem>
<listitem>
<para>Client-side manager;</para>
<para>They know only a part of the cluster view and cannot
modify it.</para>
</listitem>
</orderedlist>
<para>The following figures illustrates the communication between
the managers:</para>
<para><mediaobject>
<imageobject>
<imagedata align="center"
fileref="images/managers.png"
width="40%" scalefit="1" format="PNG"/>
</imageobject>
<caption><para>Communication between the
managers</para></caption>
</mediaobject></para>
</section>
</section>
</section>
</chapter>
<chapter xml:id="cmi.ug.conf">
<title>Configuring CMI</title>
<para>The configuration occurs at two independent levels in CMI:</para>
<orderedlist>
<listitem>
<para>The configuration of the manager of the cluster view, needed
only for servers ;</para>
</listitem>
<listitem>
<para>The configuration of the context, mandatory for all.</para>
</listitem>
</orderedlist>
<section>
<title>Configuring the manager of the cluster view</title>
<para>The manager of the cluster view can only be configured on the
server-side. The properties will be read from the file
<filename>cmi.properties</filename> when Carol is not used (see the
section dedicated to Carol for informations about it). The manager on
the client-side downloads dynamically its configuration. As a result,
all the managers on the client-side use the same configuration.</para>
<section>
<title>Common configuration of servers</title>
<para>Here is the configuration relative at a server, common at all
implementations:</para>
<para><screen># Class name of the implementation of the ServerClusterViewManager
cmi.server.impl.class=org.ow2.cmi.controller.server.impl.jgroups.JGroupsClusterViewManager <co
id="id1" />
# Domain name for the CMI MBean
cmi.server.admin.domain=CMI <co id="id2" />
# Attribute name for the CMI MBean
cmi.server.admin.mbean=CMIAdmin <co id="id3" />
# Enumeration of supported connector protocols
cmi.server.admin.connector.protocol=jrmp <co id="id4" />
# Enable or disable bind of a provider
cmi.server.provider.bind=true <co id="id5" />
# Enable or disable bind of a registry
cmi.server.registry.bind=true <co id="id6" />
# Load factor xml:id="cmi.ug.conf"
cmi.server.load=100 <co id="id7" /></screen></para>
<para><calloutlist>
<callout arearefs="id1">
<para>Indicate a name for a concrete implementation of the
interface
<interfacename>org.ow2.cmi.controller.server.ServerClusterViewManager</interfacename>.</para>
</callout>
<callout arearefs="id2">
<para>Indicate a name of domain to register MBeans when CMI is
in stand-alone. When CMI is used with Carol, the name of domain
is provided by the latter.</para>
</callout>
<callout arearefs="id3">
<para>Indicate a name to register the MBean
<interfacename>org.ow2.cmi.admin.CMIAdminMBean</interfacename>.</para>
</callout>
<callout arearefs="id4">
<para>Indicate for each protocol in the list, which JMX
connectors will be bound into the registries.</para>
</callout>
<callout arearefs="id5">
<para>True indicates that a provider of the cluster view (for
clients) will be bound for each protocol into the
registries.</para>
</callout>
<callout arearefs="id6">
<para>True indicates that clients could use the registries of
this server (for each protocol) to lookup objects that are not
clustered.</para>
</callout>
<callout arearefs="id7">
<para>Indicate the load-factor of the associated server.</para>
</callout>
</calloutlist></para>
</section>
<section>
<title>Configuration of servers using the implementation with
JGroups</title>
<para>Here is the configuration relative at a server, specific at the
implementation with JGroups:</para>
<para><screen># Filename of the jgroups conf file
cmi.server.impl.jgroups.conf=jgroups-cmi.xml <co id="id8" />
# Groupname for JGroups
cmi.server.impl.jgroups.groupname=G1 <co id="id9" />
# Timeout to wait a reconnection
cmi.server.impl.jgroups.reconnection.timeout=5000 <co id="jgroups-reco" /></screen></para>
<para><calloutlist>
<callout arearefs="id8">
<para>Indicate a filename that contains a stack to define a
channel.</para>
</callout>
<callout arearefs="id9">
<para>Indicate a name of group to define a channel.</para>
</callout>
<callout arearefs="jgroups-reco">
<para>Timeout to wait a reconnection.</para>
</callout>
</calloutlist></para>
</section>
xml:id="cmi.ug.conf"
<section>
<title>Configuration of clients</title>
<para>Here is the configuration relative at a client:</para>
<para><screen># Time to refresh the client view
cmi.client.refresh.time=50000 <co id="id10" /></screen></para>
<para><calloutlist>
<callout arearefs="id10">
<para>Indicate a delay between each update of the cluster view
by clients.</para>
</callout>
</calloutlist></para>
<note>
<para>This property must be set on the server-side, and the value
will be downloaded by clients.</para>
</note>
</section> xml:id="cmi.ug.conf"
</section>
<section>
<title>Configuring the context</title>
<para>Configuring the context needs only several additional properties
(in comparison with the settings required to create a new instance of
<classname>javax.naming.InitialContext</classname>).</para>
<section>
<title>In stand-alone</title>
<para>Here is the properties needed to generate the
environment:</para>
<para><screen># Indicate a list of provider URLs
cmi.context.provider.urls=rmi://129.183.101.165:1092,localhost:1099 <co
id="id11" />
# Indicate a class to use to create a context
cmi.context.wrapped.factory=com.sun.jndi.rmi.registry.RegistryContextFactory <co
id="id12" />
# Indicate a protocol associated with the context
cmi.context.wrapped.protocol=jrmp <co id="id13" />
# Indicate if the application is a server, default=false
cmi.mode.server=true <co id="id14" />
# Server only: Enable or disable replication, default=true
cmi.server.start.replication=true <co id="id15" /></screen></para>
<para><calloutlist>
<callout arearefs="id11">
<para>Either a list of provider URLs (on servers) for a client
(<abbrev>i.e.</abbrev> the property
<property>cmi.server.mode=false</property>), or only one
provider URL (on a local registry) for a server
(<abbrev>i.e.</abbrev> the property
<property>cmi.server.mode=true</property>).</para>
</callout>
<callout arearefs="id12">
<para>The class must implement the interface
<interfacename>javax.naming.spi.InitialContextFactory</interfacename>
to construct new contexts to read (only) the registries.</para>
</callout>
<callout arearefs="id13">
<para>Only one name of protocol is expected (while several can
be set with Carol).</para>
</callout>
<callout arearefs="id14">
<para>If this property is set at true, a local registry to
perform writes (bindings for example) is expected. If this
property is set at false, a call at a writing operation will
throw an exception of type
<exceptionname>org.ow2.cmi.jndi.context.CMINamingException</exceptionname>.</para>
</callout>
<callout arearefs="id15">
<para>True indicates that no instance of type
<interfacename>org.ow2.cmi.controller.server.ServerClusterViewManager</interfacename>
will be created.</para>
</callout>
</calloutlist></para>
</section>
<section id="sec_conf_carol">
<title>With Carol</title>
<para>With its version 2.0.0, CMI is no more treated as a protocol.
The result is that its configuration in Carol has changed.</para>
<para>Here is the properties relative to CMI, found in the file
<filename>carol.properties</filename>:</para>
<para><screen># jonas rmi activation (iiop, irmi, jrmp)
carol.protocols=jrmp <co id="id16" />
# Global property for enabling the use of cmi in carol
carol.start.cmi=true <co id="id17" />
# RMI IRMI URL
carol.irmi.url=rmi://localhost:1098 <co id="id18" />
# For each protocol, set if CMI is enabled (only for server)
carol.irmi.cmi=false <co id="id19" />
# RMI JRMP URL
carol.jrmp.url=rmi://129.183.101.165:1092,129.183.101.165:1099
carol.jrmp.cmi=true
# RMI IIOP URL
carol.iiop.url=iiop://localhost:2001
carol.iiop.cmi=false
# Server only: Enable or disable replication, default=true
cmi.server.start.replication=true</screen></para>
<calloutlist>
<callout arearefs="id16">
<para>Indicate a list of protocols to use.</para>
</callout>
<callout arearefs="id17">
<para>True indicates that CMI can be used (if enabled individually
for each protocol).</para>
</callout>
<callout arearefs="id18">
<para>As in stand-alone mode, either a list of provider URLs (on
servers) for a client, or only one provider URL (on a local
registry) for a server.</para>
</callout>
<callout arearefs="id19">
<para>True indicates that CMI will be used for this protocol. If
the property <property>carol.start.cmi</property> is set with the
value <property>false</property>, this property is ignored.</para>
</callout>
</calloutlist>
</section>
</section>
</chapter>
<chapter xml:id="cmi.ug.use">
<title>Using CMI</title>
<para>This chapter describes the use of CMI by users and
administrators.</para>
<section>
<title>Creating a context</title>
<para>The first step in the use of CMI is the creation of the context.
During this step the manager of the cluster view will be also
constructed (if it doesn't already exist).</para>
<section>
<title>In stand-alone</title>
<para>When CMI is used in stand-alone, the methods
<methodname>getCMIEnv()</methodname>,
<methodname>getCMIEnv(URL)</methodname> or
<methodname>getCMIEnv(Properties)</methodname> of the class
<classname>org.ow2.cmi.config.JNDIConfig</classname> must be used to
construct the environment that will be specified at the constructor
<methodname>InitialContext(Hashtable<?, ?>)</methodname> of
class <classname>javax.naming.InitialContext</classname>.</para>
<para>Here is an example of a construction of an instance of
<classname>org.ow2.cmi.jndi.context.CMIContext</classname> in
stand-alone:</para>
<para><example>
<title>Initializing the environment (from the file
<filename>cmi.properties</filename>) to construct a new
<classname>org.ow2.cmi.jndi.context.CMIContext</classname></title>
<screen>Hashtable<String, ?> cmiEnv = JNDIConfig.getCMIEnv();
InitialContext ic = new InitialContext(cmiEnv);</screen>
</example></para>
</section>
<section>
<title>By delegating it to Carol</title>
<para>When CMI is associated with Carol, the configuration of the
context is delegated to Carol, so no additional instruction is needed.
The configuration of Carol will be explained in <link
linkend="sec_conf_carol">a next chapter</link>.</para>
<para>Here is an example of a construction of an instance of
<classname>org.ow2.cmi.jndi.context.CMIContext</classname> with
Carol:</para>
<para><example>
<title>Initializing Carol with the file
<filename>carol.properties</filename></title>
<screen>ConfigurationRepository.init();
InitialContext ic = new InitialContext();</screen>
</example></para>
</section>
<section>
<title>By delegating it to the smart factory</title>
<para>Likewise, the creation of an instance of
<classname>org.ow2.cmi.jndi.context.CMIContext</classname> can be
delegated to the smart factory.</para>
<para>The smart factory downloads transparently the missing classes
and properties to use CMI. So, a client that uses it, doesn't need to
have in its classpath the full library of CMI. Also, because
properties (as the list of provider URLs) are downloaded before the
creation of context, they are up-to-date.</para>
<para>The smart factory is enabled by an other implementation of the
interface
<interfacename>javax.naming.spi.InitialContextFactory</interfacename>.
So to use the smart factory, clients must specify the class
<classname>org.ow2.cmi.smart.spi.SmartContextFactory</classname> as
factory.</para>
<para>Here is an example of a construction of an instance of
<classname>org.ow2.cmi.jndi.context.CMIContext</classname> with the
smart factory:</para>
<para><example>
<title>Initializing the smart factory</title>
<screen>Hashtable<String, Object> env = new Hashtable<String, Object>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "org.ow2.cmi.smart.spi.SmartContextFactory");
env.put(Context.PROVIDER_URL, "smart://localhost:2505");
InitialContext ic = new InitialContext(env);</screen>
</example></para>
</section>
</section>
<section>
<title id="chap_def_clust_obj">Defining clustered objects</title>
<para>This section describes the steps in order to define new clustered
objects.</para>
<section>
<title>The concepts</title>
<para>A clustered object is characterized by its informations about
clustering. They are of two kinds:</para>
<orderedlist>
<listitem>
<para>Declaration of a clustered object and its initial
configuration;</para>
<para>The name of cluster containing this object is a part of the
declaration.</para>
<para>The minimal and maximal sizes of the pool are a part of its
initial configuration.</para>
</listitem>
<listitem>
<para>Description of the manner to access to it (the
algorithm).</para>
<para>The policy and strategy of load-balancing are a part of the
algorithm. While policy is mandatory to define the algorithm,
strategy is optional.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Choosing an algorithm of load-balancing</title>
<para>CMI provides some standard policies and strategies. When an
object is declared belonging to a cluster, the algorithm to access to
it must be provided.</para>
<section>
<title>Using an existing algorithm</title>
<para>Standard policies:</para>
<itemizedlist>
<listitem>
<para>Round robin</para>
</listitem>
<listitem>
<para>First available</para>
</listitem>
<listitem>
<para>Random</para>
</listitem>
<listitem>
<para>HA Singleton</para>
</listitem>
</itemizedlist>
<para>Standard strategies:</para>
<itemizedlist>
<listitem>
<para>Local preference</para>
</listitem>
<listitem>
<para>Load factor sort</para>
</listitem>
<listitem>
<para>Load factor weight</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Designing a new algorithm</title>
<para>Designing a new algorithm consists in implementing
interfaces.</para>
<section>
<title>Writing a policy</title>
<para>To define its own policy, the following interface must be
implemented:</para>
</section>
<section>
<title>Writing a strategy</title>
<para>To define its own strategy, the following interface must be
implemented:</para>
</section>
</section>
</section>
<section>
<title>Configuring the algorithm</title>
<para>Adding properties to a policy allows to add dynamicity at an
algorithm, because properties are also downloaded by clients. The
following section will describe how to declare these
properties.</para>
</section>
<section>
<title>Adding the informations for clustered object</title>
<para>It exists two ways to add the informations about
clustering:</para>
<orderedlist>
<listitem>
<para>Java annotations;</para>
<para>Annotations simplify the use of CMI by avoiding adding a new
XML file. For the moment, only the class must be annotated and not
its interface.</para>
<para><warning>
<para>A JDK 1.5 or higher is required to use
annotations.</para>
</warning></para>
</listitem>
<listitem>
<para>Deployment descriptors.</para>
<para>The source code is not modified, but a XML file is
required.</para>
</listitem>
</orderedlist>
<section>
<title>With annotations</title>
<para>Firstly the class of the clustered objects must be annotated
with <interfacename>@Cluster</interfacename>.</para>
<para>Here is the definition of this annotation:</para>
<para>Next, adding the annotation
<interfacename>@Policy</interfacename> permits to declare the way to
access to the instances of this class.</para>
<para>Here is the definition of this annotation:</para>
<para>Next, a strategy can be eventually used by annotating the
class with <interfacename>@Strategy</interfacename>.</para>
<para>Here is the definition of this annotation:</para>
<para>Finally, properties can be initialized by annotating the class
with <interfacename>@Properties</interfacename>.</para>
<para>Here is the definition of this annotation:</para>
</section>
<section>
<title>With a descriptor of deployment</title>
<para>Here is the schema to define a descriptor of
deployment:</para>
</section>
</section>
<section>
<title>Binding</title>
<para>When the object is bound, the context detects that it must be
clustered. So their informations are given to the manager of the
cluster view, and this last replicates them.</para>
</section>
</section>
</chapter>
<chapter xml:id="cmi.ug.adm">
<title id="chap_admin">Administrating CMI</title>
<para>The registered MBean allows to monitor and administrate the cluster
by delegating its tasks to the manager of its JVM.</para>
<para>To connect it, the service URL is:<address>service:jmx:<protocol>:///jndi/<providerURL>/server</address></para>
</chapter>
</book>
© 2015 - 2024 Weber Informatics LLC | Privacy Policy