[Sandboss-cvs] CVS: sand/docs Deploy.html,NONE,1.1

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

Update of /cvsroot/sandboss/sand/docs
In directory usw-pr-cvs1:/tmp/cvs-serv17593

Added Files:
	Deploy.html 
Log Message:
This is a first draft of how to handle the configuration and control of a
deployment in SandBoss.  Feedback very welcome (what's missing, what's
wrong, what seems like it could be better, problems foreseen, questionable
decisions, vagueness, goodness etc).  If I don't hear anything back I have
to assume it's good enough to go with. 

To pull this into your docs page without a complete rebuild type
ant reindex

--- NEW FILE: Deploy.html ---
<HTML>
<HEAD>
  <TITLE>deployment configuration and control</TITLE>
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
</HEAD>

<BODY BGColor="#FFFFFF">

<P><CENTER><H1>deployment configuration and control<BR></H1></CENTER>

<P><B><A Name="TOC"><A HREF="#TOC">Table of Contents</A>:</B><UL>
<LI><A HREF="#intro">introduction</A>
<LI><A HREF="#deploy">apps and deploy</A>
<LI><A HREF="#configboot">bootstrapping the configuration</A>
<LI><A HREF="#configserver">the ConfigServer MBean</A>
<LI><A HREF="#implnote">implementation notes</A>
</UL>
<BR><BR>

<P><B><A Name="intro">introduction: </B><BR>

After seeing the <A HREF="../readme.txt">readme.txt</A> in the root
directory and following the directions, you presumably took a look at the
<A HREF="index.html">main documentation root</A>, and now you are looking
to deploy and run. This doc explains the process.

If you are not familiar with SAND (Structs and Nodes Development) then
you need to read at least the <A
HREF="http://www.epinova.com/docs/sandover.html">overview</A>, and preferably
some of the <A HREF="http://www.epinova.com">other available information</A>,
to understand how development works.

<P><A HREF="#TOC">TOC</A>
<BR><BR>

<P><B><A Name="deploy">apps and deploy: </B><BR>

The apps directory contains projects which will be re-used
without modification across a variety of deployments. An app has no node
instances by itself, it exists solely to be required by a deployment. A
deployment is a subproject in the deploy directory, which requires
one or more apps (the basics project is pretty much assumed).

You can define structs and nodes in both apps and deployments, but you
can only configure and run a deployment. It's up to you how you want to
segment your application source.

Every deployment contains a configuration.xml which stores the 
<A HREF="../apps/basics/docs/javadoc/org/sandboss/basics/structs/ConfigurationStruct.html">Configuration</A>
serialized to XML. Initially there is no initial data, no nodes, and only
the localhost server definition. The name defaults to the project name.

<P><A HREF="#TOC">TOC</A>
<BR><BR>

<P><B><A Name="configboot">bootstrapping the configuration: </B><BR>

Configuration of the complete application is done from a primary
configuration server (PCS). Once the system is configured, control of node
instance state can be done from any server with access to the node
instance, but the authoritative configuration.xml file is found on the PCS.
The file itself exists either in the env directory of the project (when a
development structure is present), or the top level install directory when
only the minimum components are installed.

Where reasonable, it is recommended that the PCS have the full
development structure, since it allows configuration.xml updates to be
synchronized with the code versioning system. The build process
automatically verifies that ConfigServer is known to its local JBoss
installation, otherwise this is done by the install process.

To configure the application, go to the PCS, verify JBoss is running (cd
JBOSS_HOME/bin, run) and then bring up the ConfigServer node instance on
the <A HREF="http://localhost:8082">control page</A>. The ConfigServer
loads the information from configuration.xml, and will write a new
configuration.xml in response to any changes in the system. When a node is
changed directly on another server, the changes are propagated back to the
ConfigServer on the PCS, which records the update. If the PCS is
unreachable, then the node being changed will alert the user that the
changes were not persisted back to the authoritative record.

<P><A HREF="#TOC">TOC</A>
<BR><BR>

<P><B><A Name="configserver">the ConfigServer MBean: </B><BR>

When the ConfigServer is started, it verifies registration of all the
node instances in the configuration and starts them. New node instances
can be created, and existing node instances deleted, by editing the
configuration attribute of the ConfigServer.

Every effort is made to ease viewing/editing the configuration
information (multiple choice drop down boxes, descriptive information,
validation of values etc). Quick links from the configuration to the
control interface for each node instance are provided.

The ConfigServer has a stateCheck method that will iterate through all
the node instances in the configuration and report on the state for each
one. This is a quick way to verify the system is running smoothly,
although the expectation is node function will be monitored through
event-based performance monitoring software.

<P><A HREF="#TOC">TOC</A>
<BR><BR>

<P><B><A Name="implnote">implementation notes: </B><BR>

<OL>
<LI>The editing of complex information as an attribute of an MBean is
    explicitely supported in the JMX specification.  Chapter 2 pg 39 
    states that "The AttributeType may be of any Java class, or an
    array of any Java class, provided that this type is valid in the
    MBeans run-time context or environment".  The Configuration and
    all it's components are messages, which must be available in the
    run-time context so there should be no problem here.
<LI>The loading and storage of the configuration.xml is done through
    the XML serialization/deserialization utilities.  The configuration
    is loaded at initialization time (by the ctor if no other method is
    provided in the signature).
<LI>A node can take care of registering other nodes.  Pg 116 of the spec
    states "The first responsibility of the MBean server is to be a 
    registry for MBeans. MBeans may be registered either by the 
    agent application, or by other MBeans".  You do this by retrieving 
    the MBeanServer interface and then making the call.
</OL>

<P><A HREF="#TOC">TOC</A>
<BR><BR>

<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR>
<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR>

</BODY>
</HTML>