incubator-isis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From danhayw...@apache.org
Subject svn commit: r1096936 [2/3] - in /incubator/isis/trunk: core/progmodel/src/main/java/org/apache/isis/core/progmodel/facets/ignore/ core/runtime/ core/runtime/src/main/java/org/apache/isis/core/runtime/logging/ core/src/docbkx/guide/ runtimes/dflt/ runti...
Date Tue, 26 Apr 2011 22:38:19 GMT
Modified: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml?rev=1096936&r1=1096935&r2=1096936&view=diff
==============================================================================
--- incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml (original)
+++ incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml Tue Apr 26 22:38:18 2011
@@ -52,182 +52,179 @@
     <para><emphasis>Apache Isis</emphasis> is designed to allow programmers
     rapidly develop domain-driven applications following the <ulink
     url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
-    pattern. It is made up of a core framework plus a number of alternate
-    implementations, and supports various viewers and object stores. Apache
-    Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+    pattern. It is made up of a core framework that supports supports various
+    viewers, along with <acronym>API</acronym>s and implementations relating
+    to security, the programming model, the runtime (persistence) and profile
+    stores (user preferences). <emphasis>Apache Isis</emphasis> is hosted at
+    the <ulink url="http://incubator.apache.org/isis">Apache
     Foundation</ulink>, and is licensed under <ulink
     url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
     License v2</ulink>.</para>
 
-    <para>This guide is written for ...</para>
-  </preface>
+    <para>The role of a runtime is to bootstrap the application and
+    components, and to manage the lifecycle of domain object entities.
+    Typically, this means managing their persistence and identity. In the case
+    of the default runtime, it also means providing support for client/server
+    remoting.</para>
 
-  <!-- main content -->
+    <sect1>
+      <title>Who this Guide is For</title>
 
-  <chapter id="chp.Intro">
-    <title>Introduction</title>
+      <para>This guide is written for deployers looking to configure
+      <emphasis>Isis</emphasis> to run using the default runtime, in any of
+      the supported configurations. It is divided into the following
+      parts:<itemizedlist>
+          <listitem>
+            <para>***</para>
 
-    <abstract>
-      <para>*** yada yada</para>
-    </abstract>
+            <para>This part of the guide ***</para>
+          </listitem>
 
-    <sect1>
-      <title>***</title>
+          <listitem>
+            <para>***</para>
 
-      <para><emphasis>*** yada yada</emphasis></para>
+            <para>This part of the guide ***</para>
+          </listitem>
 
-      <para>The guide is divided into *** parts:</para>
+          <listitem>
+            <para>***</para>
 
-      <itemizedlist>
-        <listitem>
-          <para>*** Introduction</para>
+            <para>This part of the guide ***</para>
+          </listitem>
+        </itemizedlist></para>
+    </sect1>
 
-          <para>This part of the guide discusses the principles and patterns
-          of the default runtime.</para>
-        </listitem>
+    <sect1>
+      <title>How this Guide relates to other Documentation</title>
 
-        <listitem>
-          <para>*** Architecture</para>
+      <para>The <emphasis>core</emphasis> documentation
+      <package>[oai:core]</package> describes common modules, including
+      reusable classes that make up the <emphasis>core runtime</emphasis>
+      <package>[oai.core:runtime]</package>. This module, the default runtime,
+      makes use of these classes, as well as other components. It also defines
+      a number of its own <acronym>sub-API</acronym>s.</para>
+    </sect1>
+  </preface>
 
-          <para>This part of the guide discusses some of the main architecture
-          elements of the default runtimes design, distinguishing and
-          explaining the reason for the applib, the core modules, the viewers,
-          the default implementations of the main APIs exposed by the core,
-          and the alternative implementations of those APIs.</para>
-        </listitem>
+  <chapter>
+    <title>Core Concepts</title>
 
-        <listitem>
-          <para>APIs</para>
+    <para></para>
 
-          <para>This part of the guide goes the (sub-)<acronym>API</acronym>s
-          that the runtime exposes</para>
-        </listitem>
+    <sect1>
+      <title>IsisContext</title>
 
-        <listitem>
-          <para>Default Implementations</para>
+      <para><emphasis>Context</emphasis></para>
 
-          <para>This part of the guide outlines the default implementations of
-          the (sub-)<acronym>API</acronym>s.</para>
-        </listitem>
+      <para>The ObjectAdapterContext provide access to the main components of
+      the NOF. If the system is started in a multi-user mode then the context
+      will hold specific components for specific execution contexts, allowing
+      the same process to access the same components and different processes
+      to access unique instances.</para>
 
-        <listitem>
-          <para>Objectstore Deployments</para>
+      <para>Each execution context will have its own Persistor, Message Broker
+      and Update Notifier.</para>
 
-          <para>This part of the guide describes how to configure the default
-          runtime to run with an objectstore.</para>
-        </listitem>
+      <para>The Reflector and Configuration are shared among all execution
+      contexts.</para>
 
-        <listitem>
-          <para>Client/Server Deployment</para>
+      <para><emphasis>Persistor</emphasis></para>
 
-          <para>This part of the guide describes how to configure the default
-          runtime to instead run in client/server mode.</para>
-        </listitem>
-      </itemizedlist>
+      <para>During startup the persistor is given a set of service objects.
+      During intialisation the persistor must determine the OIDs for these
+      service objects. If the persistor does not know about a service (by its
+      ID) from a previous run then it must generate an OID for the service and
+      persist that with the ID of the service. This allows references to be
+      held persistently to service objects despite the fact that they are
+      singletons.</para>
 
       <para></para>
 
-      <para>***</para>
-
-      <para>This guide describes the deployment options that are available
-      through using the default implementations of the core module
-      <acronym>API</acronym>s, for the most common viewers
-      (<acronym>DnD</acronym> and <acronym>HTML</acronym>). Other viewers
-      and/or alternative module implementations may require or offer different
-      deployment options. For example, the remoting alternative implementation
-      requires the bundling up of different client vs server deployments.
-      Similarly, a viewer for a mobile phone (there isn't one at the time of
-      writing but there could be in the future) would require packaging in a
-      certain way.</para>
-    </sect1>
-  </chapter>
+      <para><emphasis>Identity map</emphasis></para>
 
-  <chapter>
-    <title>***</title>
+      <para>Any object that has identity (whether it is persisted or not) must
+      be registered with the identity map. This maps two relationships: domain
+      objects to proxies and OIDs to proxies.</para>
 
-    <abstract>
-      <para>*** yada yada</para>
-    </abstract>
+      <para>Whenever a domain object is handled by the system, and before a
+      proxy is created, it must be checked against the identity map and if it
+      exists the proxy already in the identity map must be used instead of
+      creating a new proxy.</para>
 
-    <sect1>
-      <title>***</title>
+      <para></para>
 
-      <para><emphasis>*** yada yada</emphasis></para>
+      <para></para>
     </sect1>
-  </chapter>
-
-  <part>
-    <title>Modules</title>
 
-    <partintro>
-      <para></para>
+    <sect1>
+      <title>Bootstrapping using installer-registry.properties</title>
 
       <para></para>
 
       <para></para>
-    </partintro>
+    </sect1>
 
-    <chapter>
-      <title>Runtime Module</title>
+    <sect1>
+      <title>Scopes</title>
 
       <para></para>
 
       <para></para>
 
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="images/architecture.gif" scale="30" />
+        </imageobject>
+      </mediaobject>
+
       <para></para>
+    </sect1>
 
-      <sect1>
-        <title>Scopes</title>
+    <sect1>
+      <title>IdentityMap</title>
 
-        <para></para>
+      <para></para>
 
-        <para></para>
+      <para>A persistor should utilise an object-identity map (see Martin
+      Fowler's Patterns of Enterprise Application Architecture) to manage the
+      mapping of domain objects and adapters, and OIDs and adapters. For each
+      domain object the map should store a single adapter, and an OID to that
+      same adapter. The persitor can then guarantee that the same adapter is
+      always provided for a specific domain object or OID</para>
 
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="images/architecture.gif" scale="30" />
-          </imageobject>
-        </mediaobject>
+      <para></para>
+    </sect1>
 
-        <para></para>
-      </sect1>
+    <sect1>
+      <title>Profile Stores</title>
 
-      <sect1>
-        <title>Bytecode Provider API</title>
+      <para></para>
 
-        <para></para>
+      <para></para>
+    </sect1>
 
-        <para></para>
+    <sect1>
+      <title>Exploration vs Prototype Modes</title>
 
-        <para>The default runtime for <emphasis>Apache Isis</emphasis>
-        normally performs lazy loading of references and dirty tracking by
-        proxying all domain objects. Two implementations are provided, using
-        either cglib or javassist. The application archetype automatically
-        configures the use of these proxies. However, some object stores
-        (notably, the JPA object store) do not require these proxies (because
-        they add their own proxies instead); in which case these can be
-        disabled. Alternatively, you may not want to use the bytecode support,
-        in which case you can add the appropriate calls for lazy loading and
-        dirty tracking.</para>
+      <para></para>
 
-        <para>This area is covered in the {{{./applib/index.html}applib}}, but
-        there is also module-specific documentation in the
-        {{{./core/bytecode-cglib/index.html}bytecode-cglib}} and
-        {{{./core/bytecode-javassist/index.html}bytecode-javassist}}
-        modules.</para>
+      <para></para>
+    </sect1>
+  </chapter>
 
-        <para></para>
-      </sect1>
+  <part>
+    <title>Modules</title>
 
-      <sect1>
-        <title>Bootstrapping</title>
+    <partintro>
+      <para></para>
 
-        <para></para>
-      </sect1>
-    </chapter>
+      <para></para>
+
+      <para></para>
+    </partintro>
 
     <chapter>
-      <title>Runtime</title>
+      <title>Runtime Module</title>
 
       <para></para>
 
@@ -262,111 +259,103 @@
       <para></para>
 
       <sect1>
-        <title>IsisContext</title>
-
-        <para><emphasis>Context</emphasis></para>
-
-        <para>The ObjectAdapterContext provide access to the main components
-        of the NOF. If the system is started in a multi-user mode then the
-        context will hold specific components for specific execution contexts,
-        allowing the same process to access the same components and different
-        processes to access unique instances.</para>
-
-        <para>Each execution context will have its own Persistor, Message
-        Broker and Update Notifier.</para>
-
-        <para>The Reflector and Configuration are shared among all execution
-        contexts.</para>
-
-        <para><emphasis>Persistor</emphasis></para>
-
-        <para>During startup the persistor is given a set of service objects.
-        During intialisation the persistor must determine the OIDs for these
-        service objects. If the persistor does not know about a service (by
-        its ID) from a previous run then it must generate an OID for the
-        service and persist that with the ID of the service. This allows
-        references to be held persistently to service objects despite the fact
-        that they are singletons.</para>
-
-        <para><emphasis>Isis</emphasis></para>
+        <title>Bytecode Provider API</title>
 
         <para></para>
 
-        <variablelist>
-          <varlistentry>
-            <term>Oid</term>
+        <para></para>
 
-            <listitem>
-              <para></para>
+        <para>The default runtime for <emphasis>Apache Isis</emphasis>
+        normally performs lazy loading of references and dirty tracking by
+        proxying all domain objects. Two implementations are provided, using
+        either cglib or javassist. The application archetype automatically
+        configures the use of these proxies. However, some object stores
+        (notably, the JPA object store) do not require these proxies (because
+        they add their own proxies instead); in which case these can be
+        disabled. Alternatively, you may not want to use the bytecode support,
+        in which case you can add the appropriate calls for lazy loading and
+        dirty tracking.</para>
 
-              <para></para>
-            </listitem>
-          </varlistentry>
+        <para>This area is covered in the {{{./applib/index.html}applib}}, but
+        there is also module-specific documentation in the
+        {{{./core/bytecode-cglib/index.html}bytecode-cglib}} and
+        {{{./core/bytecode-javassist/index.html}bytecode-javassist}}
+        modules.</para>
 
-          <varlistentry>
-            <term>Resolved State</term>
+        <para></para>
+      </sect1>
 
-            <listitem>
-              <para></para>
-            </listitem>
-          </varlistentry>
+      <sect1>
+        <title>Bootstrapping</title>
 
-          <varlistentry>
-            <term>Version</term>
+        <para></para>
 
-            <listitem>
-              <para></para>
-            </listitem>
-          </varlistentry>
+        <para></para>
 
-          <varlistentry>
-            <term></term>
+        <para>The first thing that happens is the logging is set up so that
+        everything can be logged. This attempts to load
+        <filename>logging.properties</filename> from the
+        <filename>config</filename> directory on the filesystem and if that
+        cannot be found it will look for the same file in the same directory
+        on the classpath. If neither of these are found then a default logging
+        configuration will be programmatically installed that writes to the
+        console.</para>
 
-            <listitem>
-              <para></para>
-            </listitem>
-          </varlistentry>
-        </variablelist>
+        <para>Now that logging is initialised the container can prepare for
+        bootstrapping the system. The first task is load up all the component
+        installers, which is done by the InstallerLookupDefault class. This
+        reads the <filename>installer-registry.properties</filename> file from
+        classpath and attempts to load each class listed. Any class not found
+        is logged so it is easy to determine if a component should be
+        available. Each installer simply knows how to install a component; the
+        component is not loaded at this stage.</para>
 
-        <para><emphasis>Identity map</emphasis></para>
+        <para>Now the container knows what components are available a series
+        of option handlers (<classname>OptionHandler</classname>) are
+        intialise, with addtional one provided by the Isis container and web
+        server subclasses. These interact with the Apache CLI library to
+        provide details about the command line parameters and will lookup the
+        available components so they can be listed on the command line help.
+        With the handlers set up the command line is parsed using the Apache
+        library. If this parse fails then the library generates a error
+        message with an option summary and displays via the console and the
+        startup process terminates.</para>
 
-        <para>Any object that has identity (whether it is persisted or not)
-        must be registered with the identity map. This maps two relationships:
-        domain objects to proxies and OIDs to proxies.</para>
-
-        <para>Whenever a domain object is handled by the system, and before a
-        proxy is created, it must be checked against the identity map and if
-        it exists the proxy already in the identity map must be used instead
-        of creating a new proxy.</para>
+        <para>The last step before bootstrapping starts is to prepare the
+        ground for using congfiguration properties. Configuration details are
+        loaded by a <classname>ConfigurationBuilder</classname> object and
+        will be subsequently placed in an immutable
+        <classname>IsisConfiguration</classname> object. Immediately after
+        this has been created each handler is visited so that it can, via its
+        <methodname>primeConfigurationBuilder</methodname> method, add it
+        properties to the builder. This way each command line option is
+        converted to one or more properties of the same form as can be
+        specified in the properties files, hence we only need one way to
+        determine how the system is to be run.</para>
 
-        <para></para>
+        <para>Now that the ground has been prepared it is time for the
+        bootstrapping to begin. This is done via a call to the
+        <methodname>bootstrapIsis</methodname> method, which is where the
+        process differs for the Isis container and the web server.</para>
 
         <para></para>
-      </sect1>
-
-      <sect1>
-        <title>Services Installer</title>
 
         <para>Services are registered with the Framework at startup via the
         properties file, using the services properties. The
         <methodname>services</methodname> property itself dictates which
         service classes are to be instantiated at startup, for example:</para>
 
-        <programlisting format="linespecific">isis.services = bom.BookingFactory, bom.CustomerFactoryAndRepository, \
-  bom.LocationFactoryAndRepository
-</programlisting>
+        <programlisting format="linespecific">isis.services = com.mycompany.myapp.dom.BookingFactory,\
+                com.mycompany.myapp.dom.CustomerFactoryAndRepository, \
+                com.mycompany.myapp.dom.LocationFactoryAndRepository</programlisting>
 
         <para>The <methodname>prefix</methodname> property allows you to
         specify the common package once and, hence omit them from the classes
         in the list. The following set of properties is therefore equivalent
-        to the previous example.</para>
-
-        <programlisting format="linespecific">isis.services.prefix = bom
-isis.services = BookingFactory, CustomerFactoryAndRepository, \
-  LocationFactoryAndRepository
-</programlisting>
+        to the previous example:</para>
 
-        <para></para>
+        <programlisting format="linespecific">isis.services.prefix = com.mycompany.myapp.dom
+isis.services = BookingFactory, CustomerFactoryAndRepository, LocationFactoryAndRepository</programlisting>
 
         <para></para>
       </sect1>
@@ -420,22 +409,6 @@ isis.fixtures = BookingsFixture, Perspec
         <para></para>
 
         <sect2>
-          <title>Identity Map</title>
-
-          <para>A persistor should utilise an object-identity map (see Martin
-          Fowler's Patterns of Enterprise Application Architecture) to manage
-          the mapping of domain objects and adapters, and OIDs and adapters.
-          For each domain object the map should store a single adapter, and an
-          OID to that same adapter. The persitor can then guarantee that the
-          same adapter is always provided for a specific domain object or
-          OID</para>
-
-          <para></para>
-
-          <para></para>
-        </sect2>
-
-        <sect2>
           <title>Creating Adapters</title>
 
           <para>Numerous methods exist in the persistor (see
@@ -490,433 +463,58 @@ isis.fixtures = BookingsFixture, Perspec
       </sect1>
 
       <sect1>
-        <title>What makes up a PersistenceSession</title>
+        <title>Configuration Loading</title>
 
-        <para></para>
+        <para>*** explain the principle, how we construct from the "id" of the
+        installer.</para>
 
-        <mediaobject>
-          <imageobject>
-            <imagedata fileref="images/PersistenceSession.png" scale="30" />
-          </imageobject>
-        </mediaobject>
+        <para></para>
 
         <para></para>
-      </sect1>
 
-      <sect1 id="sec.RuntimeLauncher">
-        <title>Launcher</title>
+        <para>The configuration file (<filename class="directory"
+        moreinfo="none">isis.properties</filename>) needs to specify what
+        resources are used by the application and what fixtures to load. These
+        details are common to all the modes that the NOF can be run in.
+        Additional properties can be also specified for use in specific modes,
+        such as database connection details when using the SQL object
+        store.</para>
 
-        <para></para>
+        <para>The configuration file <filename class="directory"
+        moreinfo="none">isis.properties</filename> is always picked up. In
+        addition other properties files will be picked up, if present, based
+        on the type, viewer, persistor and connection command line switches
+        with the filename matching the option. E.g.</para>
 
-        <para></para>
+        <para>-r (or --persistor) hibernate will cause
+        <filename>persistor.properties</filename> and <filename
+        class="directory"
+        moreinfo="none">persistor_hibernate.properties</filename> to be
+        used</para>
 
-        <para>The command line container runs Isis within its own container
-        and is best suited to running from the command line where parameters
-        are used to determine what components are used and how it all
-        runs.</para>
+        <para>-t (or --type) client will cause <filename class="directory"
+        moreinfo="none">client.properties</filename> to be used</para>
 
-        <para>In essense we are running Java with the Isis class like
-        this</para>
+        <para>-v (or --viewer) dnd will cause
+        <filename>viewer.properties</filename> and <filename class="directory"
+        moreinfo="none">viewer_dnd.properties</filename> to be used</para>
 
-        <para>$ java -cp &lt;classpath&gt; org.apache.isis.runtime.IsisObject
-        &lt;parameters...&gt;</para>
+        <para>-x (or -- connector) xstream-sockets will cause
+        <filename>transport.properties</filename>,
+        <filename>transport_sockets.properties</filename>,
+        <filename>protocol.properties</filename> and
+        <filename>protocol_xstream.properties</filename> to be loaded; because
+        of the way that connector is implemented it will also load
+        <classname>persistor.properties</classname> and <filename
+        class="directory"
+        moreinfo="none">persistor_xstream-sockets.properties</filename>
+        too.</para>
 
-        <para>however we typically use a script like the one created by the
-        archetype so we can run more easily, eg</para>
+        <para>In addition a particular file can be selected with the -c
+        switch. For example</para>
 
-        <para>$ ./isis.sh &lt;parameters...&gt;</para>
-
-        <para>The Isis class immediately starts up the logging so that log
-        messages are never lost. Next the
-        <classname>InstallerLookup</classname> object is instantiated. This
-        loads up all the installers that can be found on the classpath, which
-        are listed in <filename>installer-registry.properties</filename> . (In
-        the source tree, this file physically resides in
-        <filename>core/runtime/src/main/resources/</filename>). This allows
-        Isis to be aware of all the components that are available, allowing
-        names such as xml, file, dnd and html to be used to refer to
-        components instead of their fully qualified class names. We maintain
-        this list with the framework and public available components will be
-        added to the registry list when we know about them.</para>
-
-        <para>With these details loaded Isis then parses the command line
-        parameters. If there is problem with these then a help text is
-        displayed list all the options and the program exits. With the command
-        line arguments processed Isis initializes the installers and
-        bootstraps the system.</para>
-
-        <para></para>
-
-        <para></para>
-
-        <para></para>
-
-        <para></para>
-
-        <para>If you are asked from diagnostic information then run Apache
-        Isis as follows to capture details about your machine, configuration
-        and Isis.</para>
-
-        <programlisting>$ isis.sh --diagnostics &gt; diagnostics.txt</programlisting>
-
-        <para></para>
-
-        <para></para>
-
-        <para></para>
-
-        <para>A bootstrapper takes care of loading up the Isis framework and
-        application, initialising it, and running it. When it starts up it
-        reads in a list of components and attempts to load in each one. Any
-        component that can be loaded is then available to be used and can then
-        be specified on the command line if required. Requesting a component
-        that cannot be loaded will result in an error. To resolve such an
-        error simply ensure that the component's Jar file is available on the
-        class path. All the components supplied with the framework are listed
-        in the file <filename class="directory"
-        moreinfo="none">installer-registry.properties</filename> which is part
-        of the <filename class="directory"
-        moreinfo="none">runtime-4.0.jar</filename> file.</para>
-
-        <para>During start-up Isis loads in a number of configuration files.
-        The main file, <filename class="directory"
-        moreinfo="none">isis.properties</filename>, is always loaded and must
-        be present for the framework to start up. For each of the various
-        types of persistor and viewer, there is a separate configuration file.
-        For example, for the following command line parameters</para>
-
-        <screen format="linespecific">-v dnd -r xml</screen>
-
-        <para>specifies that the viewer is to be the drag and drop (<literal
-        moreinfo="none">dnd</literal>) interface, and the persistor is to be
-        the 'xml object store'. As well as loading those components, the
-        framework will look for configuration files named
-        <filename>viewer.properties</filename>, <filename class="directory"
-        moreinfo="none">viewer_dnd.properties</filename>,
-        <filename>persistor.xml</filename> and <filename class="directory"
-        moreinfo="none">persistor_xml.properties</filename> and will load them
-        if found.</para>
-
-        <para></para>
-
-        <para></para>
-
-        <sect2>
-          <title>Class</title>
-
-          <para>The bootstrapper is the class
-          <classname>org.apache.isis.runtime.Isis</classname> and takes the
-          following options on the command line. (Note that in each case there
-          is an abbreviated, and a full, version of the option).</para>
-
-          <para>There is also an alternative bootstrapper,
-          org.apache.isis.webserver.WebServer.</para>
-
-          <para></para>
-
-          <para>*** can also use org.apache.Isis - just delegates to
-          org.apache.isis.runtime.Isis.</para>
-
-          <para></para>
-        </sect2>
-
-        <sect2>
-          <title>Configuration</title>
-
-          <screen format="linespecific">-c &lt;config file&gt;
---config &lt;config file&gt;</screen>
-
-          <para>Loads in the specified configuration file, in addition to
-          <filename class="directory"
-          moreinfo="none">isis.properties</filename> and the properties files
-          relating to the installed component.</para>
-        </sect2>
-
-        <sect2>
-          <title>Disable splash</title>
-
-          <screen format="linespecific">-s
---nosplash</screen>
-
-          <para>Prevents the splash screen from being displayed during start
-          up.</para>
-        </sect2>
-
-        <sect2>
-          <title>Help</title>
-
-          <screen format="linespecific">-h
---help</screen>
-
-          <para>Prints out the options that are available. This is dynamic so
-          that only the components that can be used are listed.</para>
-        </sect2>
-
-        <sect2>
-          <title>Logging</title>
-
-          <para>The amount of logging detail can be controlled from the
-          command line. If no flag is specified only warnings and errors are
-          output. All logging level relate to the Log4J levels, which is the
-          logging mechanism used by Isis.</para>
-
-          <screen format="linespecific">-quiet</screen>
-
-          <para>Quiet reduces logging to show errors only.</para>
-
-          <screen format="linespecific">-verbose</screen>
-
-          <para>Increases logging to show information about the system as it
-          runs.</para>
-
-          <screen format="linespecific">-debug</screen>
-
-          <para>Increases logging to show all logged entries. At this level so
-          much is logged that it will likely slow down the system if used when
-          outputting log details to the console or other slow devices.</para>
-        </sect2>
-
-        <sect2>
-          <title>Deployment Type (or Mode)</title>
-
-          <screen format="linespecific">-t &lt;mode&gt;
---type &lt;mode&gt;</screen>
-
-          <para>The framework is started up in one of several different
-          deployment modes, as listed below:</para>
-
-          <para><emphasis>exploration</emphasis> - Exploration mode is for
-          developers to explore and test their code. The framework always uses
-          an in-memory persistor and runs the fixtures at startup to ensure a
-          known state every time the system is started. The user is not
-          prompted to log in, but is automatically logged in as user
-          'exploration'. The logged in user can be changed on the fly using an
-          option with the user interface; this simply changes the user and
-          does not require an explicit login action. Also, exploration methods
-          defined in the DOM are also available to the user to do things that
-          a user would not normally be allowed to do. These are used expressly
-          for testing the system. Please note it is an error to specify a
-          persistor type in exploration mode.</para>
-
-          <para><emphasis>prototype</emphasis> - Prototype mode is for
-          demonstrating the system in realistic fashion. The user is always
-          prompted to log in at start up, and can log out and log in again
-          without losing the state of the objects. This allows a user to
-          demonstrate exactly how a system would work.</para>
-
-          <para><emphasis>single-user</emphasis> - Single user mode runs the
-          system for a single user with object persistence.</para>
-
-          <para><emphasis>client</emphasis> - Client mode provides multiple
-          users access to a server. With this mode selected the
-          <emphasis>connection</emphasis> option must also be
-          specified.</para>
-
-          <para><emphasis>server-exploration</emphasis> - Server mode, but all
-          clients will automatically be logged in as the 'exploration' user
-          (or as <classname>LoginFixture</classname> is present).</para>
-
-          <para><emphasis>server-prototype</emphasis> - Server mode, but if a
-          <classname>LoginFixture</classname> is present then all clients will
-          automatically be logged in as this user.</para>
-
-          <para><emphasis>server</emphasis> - Server mode runs Isis as a
-          server for multiple clients. With this mode selected the
-          <emphasis>connection</emphasis> option must also be
-          specified.</para>
-
-          <para>If no mode is specified, the framework will start up in
-          <emphasis>prototype</emphasis> mode.</para>
-        </sect2>
-
-        <sect2>
-          <title>Overridden properties</title>
-
-          <screen format="linespecific">-D property=value</screen>
-
-          <para>Using this flag we can pass in properties from the command
-          line that would otherwise need to specified in a configuration file.
-          This is normally used to override a property, or to temporarily
-          specify one.</para>
-        </sect2>
-
-        <sect2>
-          <title>Password</title>
-
-          <screen format="linespecific">-p &lt;password&gt;
---password &lt;password&gt;</screen>
-
-          <para>Ignored if type is prototype or not used with the user option
-          below.</para>
-
-          <para>Uses the specified password when logging the user in with the
-          username specified with <methodname>--user</methodname>.</para>
-        </sect2>
-
-        <sect2>
-          <title>Persistor</title>
-
-          <screen format="linespecific">-r &lt;persistor&gt;
---persistor &lt;persistor&gt;</screen>
-
-          <para>Ignored if type is client.</para>
-
-          <para>The persistor option allows you to choose how the objects
-          created by the system will be persisted so they are still available
-          the next time you run the system. The following options are
-          available with the current distribution, and if none is specified
-          then the in-memory persistor will be used for exploration mode and
-          xml persistor will be used for other non-client modes by
-          default.</para>
-
-          <para><emphasis>in-memory</emphasis> - A simple non-persisting
-          mechanism that will only hold the persisted object while the virtual
-          machine is running. This is used for testing and
-          demonstrating.</para>
-
-          <para><emphasis>xml</emphasis> - A simple file based mechanism that
-          encodes each object's data in an XML file. Alongside the data files
-          for the objects are instance lists listing all the files for each
-          type of object.<emphasis></emphasis></para>
-
-          <para><emphasis>&lt;class name&gt;</emphasis> - By specifying a
-          class name the boot loader will load up that class as the
-          persistor.</para>
-        </sect2>
-
-        <sect2>
-          <title>Remote connector</title>
-
-          <screen format="linespecific">-x &lt;connector&gt;
---connector &lt;connector&gt;</screen>
-
-          <para>Ignored if mode is not a client. If the type is a client then
-          a connection mechanism can be specified. Connector mechanisms
-          available are:-</para>
-
-          <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
-          mechanism (of value types) to serialize/deserialize objects, over
-          TCP/IP sockets.</para>
-
-          <para><emphasis>encoding-http</emphasis> - Uses the encoding
-          mechanism (of value types) to serialize/deserialize objects, over
-          HTTP.</para>
-
-          <para><emphasis>serializing-sockets</emphasis> - Uses Java
-          serialization (of value types) to serialize/deserialize objects,
-          over TCP/IP sockets.</para>
-
-          <para><emphasis>xstream-sockets</emphasis> - Uses the Xstream
-          library to serialize/deserialize objects to/from XML for simple
-          stream communications, over TCP/IP sockets.</para>
-        </sect2>
-
-        <sect2>
-          <title>User</title>
-
-          <screen format="linespecific">-u &lt;user name&gt;
---user &lt;user name&gt;</screen>
-
-          <para>Ignored if type is prototype.</para>
-
-          <para>Uses the specified name when logging the user in. If the
-          password is also specified (see above) then an attempt to log in
-          using the supplied user name and password is made; authentication
-          failure at this point will exit the program.</para>
-        </sect2>
-
-        <sect2>
-          <title>Viewer</title>
-
-          <screen format="linespecific">-v &lt;viewer&gt;
---viewer &lt;viewer&gt;</screen>
-
-          <para>The viewer option allows you to choose the user interface that
-          is used to access your Isis application. The following options are
-          available with the current distribution, and if none is specified
-          then the drag and drop view will be used by default.</para>
-
-          <para><emphasis>dnd</emphasis> - Drag and Drop viewer</para>
-
-          <para><emphasis>html</emphasis> - Web browser viewer - accessed via
-          standard web browser such as FireFox, Internet Explorer or
-          Opera</para>
-
-          <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
-          mechanism (of value types) to serialize/deserialize objects, over
-          TCP/IP sockets.</para>
-
-          <para><emphasis>encoding-http</emphasis> - Uses the encoding
-          mechanism (of value types) to serialize/deserialize objects, over
-          HTTP.</para>
-
-          <para><emphasis>serializing-sockets</emphasis> - Uses Java
-          serialization (of value types) to serialize/deserialize objects,
-          over TCP/IP sockets.</para>
-
-          <para><emphasis>xstream-sockets</emphasis> - Uses the Xstream
-          library to serialize/deserialize objects to/from XML for simple
-          stream communications, over TCP/IP sockets.</para>
-
-          <para><emphasis>&lt;class name&gt;</emphasis> - By specifying a
-          class name the boot loader will load up that class as the
-          viewer</para>
-        </sect2>
-      </sect1>
-
-      <sect1>
-        <title>Configuration Loading</title>
-
-        <para>*** explain the principle, how we construct from the "id" of the
-        installer.</para>
-
-        <para></para>
-
-        <para></para>
-
-        <para>The configuration file (<filename class="directory"
-        moreinfo="none">isis.properties</filename>) needs to specify what
-        resources are used by the application and what fixtures to load. These
-        details are common to all the modes that the NOF can be run in.
-        Additional properties can be also specified for use in specific modes,
-        such as database connection details when using the SQL object
-        store.</para>
-
-        <para>The configuration file <filename class="directory"
-        moreinfo="none">isis.properties</filename> is always picked up. In
-        addition other properties files will be picked up, if present, based
-        on the type, viewer, persistor and connection command line switches
-        with the filename matching the option. E.g.</para>
-
-        <para>-r (or --persistor) hibernate will cause
-        <filename>persistor.properties</filename> and <filename
-        class="directory"
-        moreinfo="none">persistor_hibernate.properties</filename> to be
-        used</para>
-
-        <para>-t (or --type) client will cause <filename class="directory"
-        moreinfo="none">client.properties</filename> to be used</para>
-
-        <para>-v (or --viewer) dnd will cause
-        <filename>viewer.properties</filename> and <filename class="directory"
-        moreinfo="none">viewer_dnd.properties</filename> to be used</para>
-
-        <para>-x (or -- connector) xstream-sockets will cause
-        <filename>transport.properties</filename>,
-        <filename>transport_sockets.properties</filename>,
-        <filename>protocol.properties</filename> and
-        <filename>protocol_xstream.properties</filename> to be loaded; because
-        of the way that connector is implemented it will also load
-        <classname>persistor.properties</classname> and <filename
-        class="directory"
-        moreinfo="none">persistor_xstream-sockets.properties</filename>
-        too.</para>
-
-        <para>In addition a particular file can be selected with the -c
-        switch. For example</para>
-
-        <para>-c <filename class="directory"
-        moreinfo="none">mysettings.properties</filename></para>
+        <para>-c <filename class="directory"
+        moreinfo="none">mysettings.properties</filename></para>
 
         <para></para>
 
@@ -1109,6 +707,10 @@ isis.fixtures=ExpenseTypes, Employees, E
         <sect2>
           <title>Users</title>
 
+          <para>*** this is also mentioned in isis-security.file...</para>
+
+          <para></para>
+
           <para>The list of users that can be switched between during
           exploration can be listed, separated by commas, with the following
           property. If no users are specified the default user "exploration"
@@ -1131,7 +733,7 @@ isis.fixtures=ExpenseTypes, Employees, E
     </chapter>
 
     <chapter>
-      <title></title>
+      <title>Runtime Module</title>
 
       <para></para>
 
@@ -1139,101 +741,117 @@ isis.fixtures=ExpenseTypes, Employees, E
 
       <para></para>
 
-      <para>There are two startup mechanisms provided with Isis: an Isis
-      container; and a web container based on Jetty. Both are run from the
-      command line and allow parameters to be specified that control its
-      behaviour, determing how logging is performed, what components are
-      loaded and so on.</para>
-
-      <para>The Isis container is run using the <classname>Isis</classname>
-      class from the core-runtime module.</para>
-
-      <para>Another way to run Isis is in a independent web container like
-      Tomcat or WebSphere. This process is dealt with later.</para>
-
       <para></para>
 
       <para></para>
 
       <sect1>
-        <title>General process</title>
+        <title>*** Component loggers</title>
 
-        <para>*** this material is probably better in the runtime module ...
-        however we should have something here that describes the main concepts
-        and classes.</para>
+        <para>*** split this out to the respective modules.</para>
 
-        <para></para>
+        <para>The framework provides a set of component loggers that
+        specifically log the use of a component, adding additional log
+        messages to the Log4j log or write out to a separate file. Additional
+        logger can also be defined for other components. These logger are
+        designed to log the parameters passed to and the the results return
+        from the requests to a component and tend to be more verbose than the
+        general logging just discussed. At present the following components
+        have loggers available:-</para>
 
-        <para>The first thing that happens is the logging is set up so that
-        everything can be logged. This attempts to load
-        <filename>logging.properties</filename> from the
-        <filename>config</filename> directory on the filesystem and if that
-        cannot be found it will look for the same file in the same directory
-        on the classpath. If neither of these are found then a default logging
-        configuration will be programmatically installed that writes to the
-        console.</para>
+        <itemizedlist>
+          <listitem>
+            <para>The object persistor -
+            <classname>ObjectPersistorLogger</classname></para>
+          </listitem>
+
+          <listitem>
+            <para>The object store -
+            <classname>ObjectStoreLogger</classname></para>
+          </listitem>
+
+          <listitem>
+            <para>The distibution interface -
+            <classname>DistributionLogger</classname></para>
+          </listitem>
+        </itemizedlist>
+
+        <para>To set up a logger create an instance of it passing in the
+        object you are logging. Then use the logger instance in place of the
+        original component. The constructors for each of the loggers are
+        overloaded so they take a component to decorate and possibly a file
+        name. If the filename is specified then the logging is done to that
+        file. If there is no file name then the events are logged via Log4j.
+        For example the object store persistor would logged by
+        replacing:</para>
+
+        <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
+isis.setObjectPersistor(persistor);</programlisting>
+
+        <para>with this, which will log request to the persistor the <filename
+        class="directory" moreinfo="none">sever-persistor.log</filename>
+        file:</para>
+
+        <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
+persistor = new ObjectManagerLogger(persistor, "server-persistor.log");
+isis.setObjectPersistor(persistor);</programlisting>
+
+        <para>Please note that the log files, when used, are created when the
+        logger is instantiated and will overwrite any exsiting file. This is
+        not normally a problem as we are interested in the activities during
+        an entire session. However on a stateless server where the component
+        is being recreated each time the continual recreation of the file
+        could be a problem.</para>
+
+        <sect2>
+          <title>Defining a logger</title>
 
-        <para>Now that logging is initialised the container can prepare for
-        bootstrapping the system. The first task is load up all the component
-        installers, which is done by the InstallerLookupDefault class. This
-        reads the <filename>installer-registry.properties</filename> file from
-        classpath and attempts to load each class listed. Any class not found
-        is logged so it is easy to determine if a component should be
-        available. Each installer simply knows how to install a component; the
-        component is not loaded at this stage.</para>
+          <para>To define a logger extend the Logger class, providing a
+          suitable constructor, and implement the
+          <methodname>getDecoratedClass</methodname> so it passes back the
+          <classname>Class</classname> object of the class being decorated
+          (this allows the Log4j logger to log messages as that class rather
+          than as a separate class). Within the subclass you can use the
+          following methods:</para>
 
-        <para>Now the container knows what components are available a series
-        of option handlers (<classname>OptionHandler</classname>) are
-        intialise, with addtional one provided by the Isis container and web
-        server subclasses. These interact with the Apache CLI library to
-        provide details about the command line parameters and will lookup the
-        available components so they can be listed on the command line help.
-        With the handlers set up the command line is parsed using the Apache
-        library. If this parse fails then the library generates a error
-        message with an option summary and displays via the console and the
-        startup process terminates.</para>
+          <itemizedlist>
+            <listitem>
+              <para><emphasis> <methodname>void log(String
+              message)</methodname> </emphasis></para>
 
-        <para>The last step before bootstrapping starts is to prepare the
-        ground for using congfiguration properties. Configuration details are
-        loaded by a <classname>ConfigurationBuilder</classname> object and
-        will be subsequently placed in an immutable
-        <classname>IsisConfiguration</classname> object. Immediately after
-        this has been created each handler is visited so that it can, via its
-        <methodname>primeConfigurationBuilder</methodname> method, add it
-        properties to the builder. This way each command line option is
-        converted to one or more properties of the same form as can be
-        specified in the properties files, hence we only need one way to
-        determine how the system is to be run.</para>
+              <para>output a log entry with the specified message.</para>
+            </listitem>
 
-        <para>Now that the ground has been prepared it is time for the
-        bootstrapping to begin. This is done via a call to the
-        <methodname>bootstrapIsis</methodname> method, which is where the
-        process differs for the Isis container and the web server.</para>
+            <listitem>
+              <para><emphasis> <methodname>void log(String message, Object
+              result)</methodname> </emphasis></para>
 
-        <para></para>
+              <para>output a log entry with the specified message and the
+              specified result. This is useful when needing to show both the
+              entry and exit states, or the paramters and the return
+              value.</para>
+            </listitem>
 
-        <para></para>
-      </sect1>
-    </chapter>
+            <listitem>
+              <para><emphasis> <methodname>void close()</methodname>
+              </emphasis></para>
 
-    <chapter id="chp.ObjectStoreApi">
-      <title>Object Store API</title>
+              <para>closes the file that is being written to.</para>
+            </listitem>
+          </itemizedlist>
 
-      <abstract>
-        <para>***</para>
-      </abstract>
+          <para></para>
 
-      <sect1>
-        <title></title>
+          <para></para>
 
-        <para></para>
+          <para></para>
 
-        <para></para>
+          <para></para>
+        </sect2>
+      </sect1>
 
-        <note>
-          <para>TODO: tidy up the following paras, were just copied/pasted in
-          from APT</para>
-        </note>
+      <sect1>
+        <title>Bytecode Enhancement API</title>
 
         <para></para>
 
@@ -1252,40 +870,43 @@ isis.fixtures=ExpenseTypes, Employees, E
       </sect1>
 
       <sect1>
-        <title>Alternative Implementations</title>
+        <title>Persistor API</title>
 
         <para></para>
       </sect1>
 
       <sect1>
-        <title>Writing your own Object Store</title>
+        <title>Object Store API</title>
 
         <para></para>
 
-        <para>When a object is persisted the object store's
-        <methodname>createCreateObjectCommand</methodname> method is called.
-        This create a command object (see GoF Patterns books), which will
-        later be processed when the transaction is be commited. All
-        persistence actions (create, destroy and save) are collected together
-        until this point. This way when a transaction is aborted all commands
-        can be thrown away without recourse to the database. Specifically it
-        is the <methodname>execute</methodname> method that is called on the
-        command, and this command runs an insert command agains the the
-        database.</para>
-
         <para></para>
-      </sect1>
-    </chapter>
 
-    <chapter id="chp.ProfileStoreApi">
-      <title>Profile Store API and Implementations</title>
+        <sect2>
+          <title>Writing your own Object Store</title>
+
+          <para>*** do we want to include this section ... it'll be somewhat
+          long!</para>
 
-      <abstract>
-        <para>***</para>
-      </abstract>
+          <para></para>
+
+          <para>When a object is persisted the object store's
+          <methodname>createCreateObjectCommand</methodname> method is called.
+          This create a command object (see GoF Patterns books), which will
+          later be processed when the transaction is be commited. All
+          persistence actions (create, destroy and save) are collected
+          together until this point. This way when a transaction is aborted
+          all commands can be thrown away without recourse to the database.
+          Specifically it is the <methodname>execute</methodname> method that
+          is called on the command, and this command runs an insert command
+          agains the the database.</para>
+
+          <para></para>
+        </sect2>
+      </sect1>
 
       <sect1>
-        <title></title>
+        <title>Profile Store API</title>
 
         <para></para>
 
@@ -1322,561 +943,609 @@ isis.fixtures=ExpenseTypes, Employees, E
 
         <para></para>
 
-        <note>
-          <para>TODO: tidy up the following paras, were just copied/pasted in
-          from APT</para>
-        </note>
+        <para></para>
+
+        <para>To store profiles (during exploration) for users the a profile
+        store must be specified.</para>
+
+        <para>On the command line use -e xml to store them in an XML.</para>
+
+        <para>Without this the profile will simply be kept in memory, and lost
+        on exit.</para>
 
         <para></para>
 
-        <para>***</para>
+        <sect2>
+          <title>Setting up Perspectives (Profile Fixtures)</title>
+
+          <para></para>
+
+          <para></para>
+
+          <para>Perspectives allow the set of services available to a user (eg
+          as icons in the DnD viewer) to be customized for that user. Since
+          these services represent the "start points" for the user to interact
+          with the domain model, they in a sense define an application on a
+          per-user basis.</para>
+
+          <para>The perspectives are stored in user-profiles, which are a
+          persistence mechanism independent of the object store. (The intent
+          is for user profiles to store additional information for use by
+          viewers, for example allowing a user to reskin an application or
+          change colors or fonts. As of NOF 4.0 the functionality provided is
+          still limited, however).</para>
+
+          <para>The key here is that if a user logs in and no perspective
+          exists for that user then one will be created for them. The new
+          perspective will be a copy of the 'template' perspective, or, if
+          none was defined, a perspective containing all the known services.
+          To create a template perspective add a perspective fixture that
+          calls <methodname>saveAsDefault()</methodname>, rather than
+          <methodname>saveForUser()</methodname> for a named user, as shown
+          below.</para>
+
+          <programlisting>public class PerspectivesFixture extends UserProfileFixture {
+    @Override
+    protected void installProfiles() {
+        Profile profile = newUserProfile();
+        Perspective perspective = profile.newPerspective("ECS");
+        perspective.addToServices(LocationFactory.class);
+        perspective.addToServices(CustomerRepository.class);
+        perspective.addToServices(PaymentMethodFactory.class);
+        
+        saveAsDefault(profile);
+    }
+}
+</programlisting>
+
+          <para>With that set up, when a new user now logs in they will see
+          three service icons on the screen for locations, customers and
+          payment methods. On the drag and drop user interface the user can
+          add and remove services from their perspective. To remove a service
+          icon right-click on the grey border and select the close option. To
+          add a service select the Services... option from the application
+          menu (accessed by right-clicking on the application background) and
+          drag the required service onto the desktop. Unfortunately there is
+          no similar mechanism available on the HTML user interface so you
+          will need to modify the created perspectives via the DND UI.</para>
+        </sect2>
+      </sect1>
+    </chapter>
+
+    <chapter>
+      <title>Webapp Module</title>
+
+      <para></para>
+
+      <para>The webapp module is a small module that provides reusable servlet
+      context listeners and filters to webapp viewers. They include:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><classname>IsisWebAppBootstrapper</classname> which is a
+          servlet context listener to bootstrap an Isis runtime and bind to
+          the servlet context</para>
+        </listitem>
+
+        <listitem>
+          <para><classname>IsisSessionFilter</classname> which is a filter
+          used to creating an IsisSession for each request (the Open session
+          in View pattern)</para>
+        </listitem>
+
+        <listitem>
+          <para><classname>ResourceServlet</classname> which serves up static
+          content from the specified resource</para>
+        </listitem>
+
+        <listitem>
+          <para><classname>StaticContentFilter</classname> which decorates
+          static content with headers for caching</para>
+        </listitem>
+      </itemizedlist>
+
+      <para><note>
+          <para>The <classname>ResourceServlet</classname> and
+          <classname>StaticContentFilter</classname> will likely move back to
+          core framework because they are likely to be of use to most runtime
+          implementations.</para>
+        </note></para>
+
+      <para>Not every webapp-based viewer is required to use these classes;
+      refer to their documentation for exact details of what should reside in
+      the web.xml.</para>
+
+      <para></para>
+    </chapter>
+
+    <chapter>
+      <title>Webserver Module</title>
+
+      <para></para>
+
+      <para>The webserver module is intended to make it easy to run
+      webapp-based viewers, using the webapp as defined in
+      <filename>src/main/webapp/WEB-INF/web.xml</filename>.</para>
+
+      <para>This is a useful facility to have during development, but is not
+      (expected to be) needed for deployment. In essence all the module does
+      is to bundle up Jetty.</para>
+
+      <para>An alternative would be to use <code>mvn jetty:run</code>; this
+      module is for when you'd rather just run a standalone program (ie, with
+      a <methodname>main()</methodname> in it) without the overhead of
+      <emphasis>Maven</emphasis>.</para>
+
+      <para></para>
+
+      <para></para>
+
+      <para>There is also an alternative bootstrapper,
+      org.apache.isis.webserver.WebServer.</para>
+
+      <para></para>
+
+      <para></para>
+
+      <sect1>
+        <title></title>
+
+        <para></para>
+
+        <sect2>
+          <title>Properties</title>
+
+          <para>The embedded web server (implemented by Jetty) has only one
+          properties</para>
+
+          <programlisting format="linespecific">isis.embedded-web-server.port=8080</programlisting>
+
+          <para>Which specifies the port to use when prototyping.</para>
+        </sect2>
+      </sect1>
+    </chapter>
+
+    <chapter>
+      <title>Remoting Modules</title>
+
+      <para></para>
+
+      <para></para>
+
+      <para></para>
+
+      <para>There are two startup mechanisms provided with Isis: an Isis
+      container; and a web container based on Jetty. Both are run from the
+      command line and allow parameters to be specified that control its
+      behaviour, determing how logging is performed, what components are
+      loaded and so on.</para>
+
+      <para>The Isis container is run using the <classname>Isis</classname>
+      class from the core-runtime module.</para>
+
+      <para>Another way to run Isis is in a independent web container like
+      Tomcat or WebSphere. This process is dealt with later.</para>
+
+      <para></para>
+
+      <para></para>
+    </chapter>
+  </part>
+
+  <part>
+    <title>Runtime APIs</title>
 
-        <para></para>
-      </sect1>
+    <chapter>
+      <title>Bytecode Enhancement API</title>
 
-      <sect1>
-        <title>Alternative Implementations</title>
+      <para></para>
 
-        <para></para>
+      <para></para>
+    </chapter>
 
-        <para></para>
+    <chapter id="chp.ObjectStoreApi">
+      <title>Persistor API and Object Store API</title>
 
-        <para></para>
-      </sect1>
+      <abstract>
+        <para>***</para>
+      </abstract>
 
       <sect1>
         <title></title>
 
         <para></para>
 
-        <para>To store profiles (during exploration) for users the a profile
-        store must be specified.</para>
-
-        <para>On the command line use -e xml to store them in an XML.</para>
+        <para></para>
 
-        <para>Without this the profile will simply be kept in memory, and lost
-        on exit.</para>
+        <note>
+          <para>TODO: tidy up the following paras, were just copied/pasted in
+          from APT</para>
+        </note>
 
         <para></para>
       </sect1>
     </chapter>
+  </part>
 
-    <chapter>
-      <title>Runtime Module</title>
+  <part>
+    <title>Deployment</title>
 
-      <para></para>
+    <chapter>
+      <title>Running in Development</title>
 
-      <para></para>
+      <para>*** ie, not deployed, just running immediately.</para>
 
       <para></para>
 
       <para></para>
 
-      <para></para>
+      <sect1 id="sec.RuntimeLauncher">
+        <title>Bootstrapping (Isis launcher)</title>
 
-      <sect1>
-        <title>Component loggers</title>
+        <para></para>
 
-        <para>The NOF provides a set of component loggers that specifically
-        log the use of a component, adding additional log messages to the
-        Log4j log or write out to a separate file. Additional logger can also
-        be defined for other components. These logger are designed to log the
-        parameters passed to and the the results return from the requests to a
-        component and tend to be more verbose than the general logging just
-        discussed. At present the following components have loggers
-        available:-</para>
+        <para></para>
 
-        <itemizedlist>
-          <listitem>
-            <para>The object persistor -
-            <classname>ObjectPersistorLogger</classname></para>
-          </listitem>
+        <para>The command line container runs Isis within its own container
+        and is best suited to running from the command line where parameters
+        are used to determine what components are used and how it all
+        runs.</para>
 
-          <listitem>
-            <para>The object store -
-            <classname>ObjectStoreLogger</classname></para>
-          </listitem>
+        <para>In essense we are running Java with the Isis class like
+        this:</para>
 
-          <listitem>
-            <para>The distibution interface -
-            <classname>DistributionLogger</classname></para>
-          </listitem>
-        </itemizedlist>
+        <para>$ java -cp &lt;classpath&gt;
+        org.apache.isis.runtimes.dflt.runtime.Isis
+        &lt;parameters...&gt;</para>
 
-        <para>To set up a logger create an instance of it passing in the
-        object you are logging. Then use the logger instance in place of the
-        original component. The constructors for each of the loggers are
-        overloaded so they take a component to decorate and possibly a file
-        name. If the filename is specified then the logging is done to that
-        file. If there is no file name then the events are logged via Log4j.
-        For example the object store persistor would logged by
-        replacing:</para>
+        <para>however we typically use a script like the one created by the
+        archetype so we can run more easily, eg</para>
 
-        <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
-isis.setObjectPersistor(persistor);</programlisting>
+        <para>$ ./isis.sh &lt;parameters...&gt;</para>
 
-        <para>with this, which will log request to the persistor the <filename
-        class="directory" moreinfo="none">sever-persistor.log</filename>
-        file:</para>
+        <para>The Isis class immediately starts up the logging so that log
+        messages are never lost. Next the
+        <classname>InstallerLookup</classname> object is instantiated. This
+        loads up all the installers that can be found on the classpath, which
+        are listed in <filename>installer-registry.properties</filename> . (In
+        the source tree, this file physically resides in
+        <filename>core/runtime/src/main/resources/</filename>). This allows
+        Isis to be aware of all the components that are available, allowing
+        names such as xml, file, dnd and html to be used to refer to
+        components instead of their fully qualified class names. We maintain
+        this list with the framework and public available components will be
+        added to the registry list when we know about them.</para>
 
-        <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
-persistor = new ObjectManagerLogger(persistor, "server-persistor.log");
-isis.setObjectPersistor(persistor);</programlisting>
+        <para>With these details loaded Isis then parses the command line
+        parameters. If there is problem with these then a help text is
+        displayed list all the options and the program exits. With the command
+        line arguments processed Isis initializes the installers and
+        bootstraps the system.</para>
 
-        <para>Please note that the log files, when used, are created when the
-        logger is instantiated and will overwrite any exsiting file. This is
-        not normally a problem as we are interested in the activities during
-        an entire session. However on a stateless server where the component
-        is being recreated each time the continual recreation of the file
-        could be a problem.</para>
+        <para></para>
 
-        <sect2>
-          <title>Defining a logger</title>
+        <para></para>
 
-          <para>To define a logger extend the Logger class, providing a
-          suitable constructor, and implement the
-          <methodname>getDecoratedClass</methodname> so it passes back the
-          <classname>Class</classname> object of the class being decorated
-          (this allows the Log4j logger to log messages as that class rather
-          than as a separate class). Within the subclass you can use the
-          following methods:</para>
+        <para></para>
 
-          <itemizedlist>
-            <listitem>
-              <para><emphasis> <methodname>void log(String
-              message)</methodname> </emphasis></para>
+        <para></para>
 
-              <para>output a log entry with the specified message.</para>
-            </listitem>
+        <para>If you are asked from diagnostic information then run Apache
+        Isis as follows to capture details about your machine, configuration
+        and Isis.</para>
 
-            <listitem>
-              <para><emphasis> <methodname>void log(String message, Object
-              result)</methodname> </emphasis></para>
+        <programlisting>$ isis.sh --diagnostics &gt; diagnostics.txt</programlisting>
 
-              <para>output a log entry with the specified message and the
-              specified result. This is useful when needing to show both the
-              entry and exit states, or the paramters and the return
-              value.</para>
-            </listitem>
+        <para></para>
 
-            <listitem>
-              <para><emphasis> <methodname>void close()</methodname>
-              </emphasis></para>
+        <para></para>
 
-              <para>closes the file that is being written to.</para>
-            </listitem>
-          </itemizedlist>
+        <para></para>
 
-          <para></para>
+        <para>A bootstrapper takes care of loading up the Isis framework and
+        application, initialising it, and running it. When it starts up it
+        reads in a list of components and attempts to load in each one. Any
+        component that can be loaded is then available to be used and can then
+        be specified on the command line if required. Requesting a component
+        that cannot be loaded will result in an error. To resolve such an
+        error simply ensure that the component's Jar file is available on the
+        class path. All the components supplied with the framework are listed
+        in the file <filename class="directory"
+        moreinfo="none">installer-registry.properties</filename> which is part
+        of the JAR file for <package>[oai.runtimes.dflt:runtime]</package>
+        module.</para>
 
-          <para></para>
+        <para>During start-up Isis loads in a number of configuration files.
+        The main file, <filename class="directory"
+        moreinfo="none">isis.properties</filename>, is always loaded and must
+        be present for the framework to start up. For each of the various
+        types of persistor and viewer, there is a separate configuration file.
+        For example, for the following command line parameters</para>
 
-          <para></para>
+        <screen format="linespecific">-v dnd -r xml</screen>
 
-          <para></para>
-        </sect2>
-      </sect1>
+        <para>specifies that the viewer is to be the drag and drop (<literal
+        moreinfo="none">dnd</literal>) interface, and the persistor is to be
+        the 'xml object store'. As well as loading those components, the
+        framework will look for configuration files named
+        <filename>viewer.properties</filename>, <filename class="directory"
+        moreinfo="none">viewer_dnd.properties</filename>,
+        <filename>persistor.xml</filename> and <filename class="directory"
+        moreinfo="none">persistor_xml.properties</filename> and will load them
+        if found.</para>
 
-      <sect1>
-        <title>Diagnostics (Logging)</title>
+        <para></para>
 
         <para></para>
 
         <sect2>
-          <title>Snapshot appenders</title>
-
-          <para>The NOF provides a number of appenders that create a snapshot
-          of the recently logged events instead of capturing all events since
-          the system started. The benefits here are twofold. First, writing to
-          the appenders is minimised as they are only written when errors
-          occur or the user demands it. Second, the partial log can be
-          automatically sent over the network to someone who needs to know
-          when things have gone wrong.</para>
-
-          <para>All the snapshot appends support the same basic
-          properties:-</para>
+          <title>Class</title>
 
-          <itemizedlist>
-            <listitem>
-              <para><emphasis> <methodname>addInfo</methodname>
-              </emphasis></para>
+          <para>The bootstrapper is the class
+          <classname>org.apache.isis.runtime.Isis</classname> and takes the
+          following options on the command line. (Note that in each case there
+          is an abbreviated, and a full, version of the option).</para>
 
-              <para>(boolean) indicates whether to prepend details about the
-              machine, os and Java to log, eg</para>
+          <para></para>
 
-              <programlisting format="linespecific">Snapshot:- Thu Dec 01 14:34:24 GMT 2005
-  R Matthews
-  Windows XP (x86) 5.1
-  Java HotSpot(TM) Client VM 1.4.2_04-b05
-  Version  000000</programlisting>
-            </listitem>
+          <para></para>
 
-            <listitem>
-              <para><emphasis> <methodname>bufferSize</methodname>
-              </emphasis></para>
+          <para>*** can also use org.apache.Isis - just delegates to
+          org.apache.isis.runtime.Isis.</para>
 
-              <para>(integer) the number of events to write out to the
-              snapshot. Defaults to 512 events.</para>
-            </listitem>
+          <para></para>
+        </sect2>
 
-            <listitem>
-              <para><emphasis> <methodname>locationInfo</methodname>
-              </emphasis></para>
+        <sect2>
+          <title>Configuration</title>
 
-              <para>(boolean) whether to capture the details of where in the
-              code the event was generated. Note - capturing this information
-              can be quite expensive.</para>
-            </listitem>
+          <screen format="linespecific">-c &lt;config file&gt;
+--config &lt;config file&gt;</screen>
 
-            <listitem>
-              <para><emphasis> <methodname>evaluatorClass</methodname>
-              </emphasis></para>
+          <para>Loads in the specified configuration file, in addition to
+          <filename class="directory"
+          moreinfo="none">isis.properties</filename> and the properties files
+          relating to the installed component.</para>
+        </sect2>
 
-              <para>(<classname>org.apache.log4j.spi.TriggeringEventEvaluator</classname>)
-              a trigger that determines when a snapshot should be created. The
-              trigger object is given each event that is logged and flags when
-              to produce a snapsho.</para>
-
-              <para>When not trigger is specified a default trigger is applied
-              that triggers a snapshot when an event of level ERROR or FATAL
-              occurs.</para>
-            </listitem>
-          </itemizedlist>
+        <sect2>
+          <title>Disable splash</title>
 
-          <sect3>
-            <title>File snapshot appender</title>
+          <screen format="linespecific">-s
+--nosplash</screen>
 
-            <para>The <classname>FileSnapshotAppender</classname> writes the
-            snapshot to timestamped file. The following properties can be
-            specified:-</para>
-
-            <itemizedlist>
-              <listitem>
-                <para><emphasis><methodname>directory</methodname></emphasis></para>
-
-                <para>The directory path where the files are to be created. If
-                none is specified then the working directory will be
-                used.</para>
-              </listitem>
-
-              <listitem>
-                <para><emphasis><methodname>extension</methodname></emphasis></para>
-
-                <para>The extension type to append to the file name.</para>
-              </listitem>
-
-              <listitem>
-                <para><emphasis><methodname>fileName</methodname></emphasis></para>
-
-                <para>The base name of the log file, which will have timestamp
-                appended. Defaults to 'log-snapshot-'.</para>
-              </listitem>
-            </itemizedlist>
-
-            <para>The following example writes xml snapshots to the logs
-            directory to files ending with '.xml'.</para>
-
-            <programlisting format="linespecific">log4j.appender.Snapshot=org.apache.isis.utility.logging.FileSnapshotAppender
-log4j.appender.Snapshot.bufferSize=1024
-log4j.appender.Snapshot.addInfo=true
-log4j.appender.Snapshot.locationInfo=true
-log4j.appender.Snapshot.directory=logs
-log4j.appender.Snapshot.extension=xml
-log4j.appender.Snapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>
-          </sect3>
-
-          <sect3>
-            <title>Popup snapshot appender</title>
-
-            <para>The <classname>PopupSnapshotAppender</classname> displays a
-            popup dialog showing the snapshot.</para>
-
-            <mediaobject>
-              <imageobject>
-                <imagedata align="left" fileref="images/popup-snapshot.png"
-                           format="PNG" width="12.5cm" />
-              </imageobject>
-            </mediaobject>
-
-            <para>Do not use this on a server as there will be no one sitting
-            in front of it to see it. It has no properties so its
-            configuration is short.</para>
-
-            <programlisting format="linespecific">log4j.appender.Popup=org.apache.isis.utility.logging.PopupSnapshotAppender
-log4j.appender.Popup.layout=org.apache.log4j.PatternLayout
-log4j.appender.Popup.layout.ConversionPattern=%-5r [%-20c{1} %-10t %-5p]  %m%n
-</programlisting>
-          </sect3>
+          <para>Prevents the splash screen from being displayed during start
+          up.</para>
+        </sect2>
 
-          <sect3>
-            <title>Email snapshot appender</title>
+        <sect2>
+          <title>Help</title>
 
-            <para>The <classname>SmtpSnapshotAppender</classname> generates an
-            email with the snapshot in it and sends it to a specified
-            recipient. The following properties can be specified:-</para>
+          <screen format="linespecific">-h
+--help</screen>
 
-            <itemizedlist>
-              <listitem>
-                <para><emphasis><methodname>server</methodname></emphasis></para>
+          <para>Prints out the options that are available. This is dynamic so
+          that only the components that can be used are listed.</para>
+        </sect2>
 
-                <para>Address of the email server</para>
-              </listitem>
+        <sect2>
+          <title>Logging</title>
 
-              <listitem>
-                <para><emphasis><methodname>port</methodname></emphasis></para>
+          <para>The amount of logging detail can be controlled from the
+          command line. If no flag is specified only warnings and errors are
+          output. All logging level relate to the Log4J levels, which is the
+          logging mechanism used by Isis.</para>
 
-                <para>The port the server listen on for SMTP requests.
-                Defaults to port 25.</para>
-              </listitem>
+          <screen format="linespecific">-quiet</screen>
 
-              <listitem>
-                <para><emphasis><methodname>recipient</methodname></emphasis></para>
+          <para>Quiet reduces logging to show errors only.</para>
 
-                <para>Email address to send the snapshot to.</para>
-              </listitem>
+          <screen format="linespecific">-verbose</screen>
 
-              <listitem>
-                <para><emphasis><methodname>domain</methodname></emphasis></para>
+          <para>Increases logging to show information about the system as it
+          runs.</para>
 
-                <para>The address that client connects to the server with.
-                Some email servers validate the sender's address in the MAIL
-                FROM command so you may need to specify a real address
-                here.</para>
-              </listitem>
-            </itemizedlist>
+          <screen format="linespecific">-debug</screen>
 
-            <para>The following example sends a short HTML snapshot logs to
-            logs@support.acme.com, via the email server at my.emailserver.com
-            using port 25.</para>
+          <para>Increases logging to show all logged entries. At this level so
+          much is logged that it will likely slow down the system if used when
+          outputting log details to the console or other slow devices.</para>
+        </sect2>
 
-            <programlisting format="linespecific">log4j.appender.EmailSnapshot=org.apache.isis.utility.logging.SmtpSnapshotAppender
-log4j.appender.EmailSnapshot.bufferSize=50
-log4j.appender.EmailSnapshot.addInfo=true
-log4j.appender.EmailSnapshot.server=my.emailserver.com
-log4j.appender.EmailSnapshot.port=25
-log4j.appender.EmailSnapshot.recipient=logs@support.acme.com
-log4j.appender.EmailSnapshot.layout=org.apache.log4j.HTMLLayout</programlisting>
-          </sect3>
+        <sect2>
+          <title>Deployment Type (or Mode)</title>
 
-          <sect3>
-            <title>Socket snapshot appender</title>
+          <screen format="linespecific">-t &lt;mode&gt;
+--type &lt;mode&gt;</screen>
 
-            <para>The <classname>SocketSnapshotAppender</classname>
-            establishes a socket connection to a server and passes across the
-            the snapshot. This is designed to be used with
-            <classname>SnapshotServer</classname>, which collects collects
-            snapshots from multiple clients.</para>
+          <para>The framework is started up in one of several different
+          deployment modes, as listed below:</para>
 
-            <para>The following example sends an XML snapshot to a server on a
-            private network.</para>
+          <para><emphasis>exploration</emphasis> - Exploration mode is for
+          developers to explore and test their code. The framework always uses
+          an in-memory persistor and runs the fixtures at startup to ensure a
+          known state every time the system is started. The user is not
+          prompted to log in, but is automatically logged in as user
+          'exploration'. The logged in user can be changed on the fly using an
+          option with the user interface; this simply changes the user and
+          does not require an explicit login action. Also, exploration methods
+          defined in the DOM are also available to the user to do things that
+          a user would not normally be allowed to do. These are used expressly
+          for testing the system. Please note it is an error to specify a
+          persistor type in exploration mode.</para>
 
-            <programlisting format="linespecific">log4j.appender.SocketSnapshot=org.apache.isis.utility.logging.SocketSnapshotAppender
-log4j.appender.SocketSnapshot.bufferSize=1024
-log4j.appender.SocketSnapshot.addInfo=true
-log4j.appender.SocketSnapshot.server=191.168.1.1
-log4j.appender.SocketSnapshot.port=12345
-log4j.appender.SocketSnapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>
+          <para><emphasis>prototype</emphasis> - Prototype mode is for
+          demonstrating the system in realistic fashion. The user is always
+          prompted to log in at start up, and can log out and log in again
+          without losing the state of the objects. This allows a user to
+          demonstrate exactly how a system would work.</para>
 
-            <para>The snaphot server should be directed to a maching running
-            the server. The server is run using the following command:</para>
+          <para><emphasis>single-user</emphasis> - Single user mode runs the
+          system for a single user with object persistence.</para>
 
-            <screen format="linespecific">java -cp isis.jar org.apache.isis.utility.logging.SnapshotServer</screen>
+          <para><emphasis>client</emphasis> - Client mode provides multiple
+          users access to a server. With this mode selected the
+          <emphasis>connection</emphasis> option must also be
+          specified.</para>
 
-            <para></para>
+          <para><emphasis>server-exploration</emphasis> - Server mode, but all
+          clients will automatically be logged in as the 'exploration' user
+          (or as <classname>LoginFixture</classname> is present).</para>
 
-            <para>The server needs a properties file with the following
-            properties defined (with the prefix
-            <methodname>isis.snapshotserver.</methodname>):-</para>
+          <para><emphasis>server-prototype</emphasis> - Server mode, but if a
+          <classname>LoginFixture</classname> is present then all clients will
+          automatically be logged in as this user.</para>
 
-            <itemizedlist>
-              <listitem>
-                <para><emphasis><methodname>server</methodname></emphasis></para>
+          <para><emphasis>server</emphasis> - Server mode runs Isis as a
+          server for multiple clients. With this mode selected the
+          <emphasis>connection</emphasis> option must also be
+          specified.</para>
 
-                <para>Address of the server.</para>
-              </listitem>
+          <para>If no mode is specified, the framework will start up in
+          <emphasis>prototype</emphasis> mode.</para>
+        </sect2>
 
-              <listitem>
-                <para><emphasis><methodname>port</methodname></emphasis></para>
+        <sect2>
+          <title>Overridden properties</title>
 
-                <para>The port the server listens on for logging requests.
-                Defaults to port 9289.</para>
-              </listitem>
+          <screen format="linespecific">-D property=value</screen>
 
-              <listitem>
-                <para><emphasis><methodname>directory</methodname></emphasis></para>
+          <para>Using this flag we can pass in properties from the command
+          line that would otherwise need to specified in a configuration file.
+          This is normally used to override a property, or to temporarily
+          specify one.</para>
+        </sect2>
 
-                <para>The directory path where the transferred files are to be
-                saved. If none is specified then the working directory will be
-                used.</para>
-              </listitem>
+        <sect2>
+          <title>Password</title>
 
-              <listitem>
-                <para><emphasis><methodname>fileName</methodname></emphasis></para>
+          <screen format="linespecific">-p &lt;password&gt;
+--password &lt;password&gt;</screen>
 
-                <para>The base name of the log file, which will have timestamp
-                appended. Defaults to 'log-snapshot-'.</para>
-              </listitem>
+          <para>Ignored if type is prototype or not used with the user option
+          below.</para>
 
-              <listitem>
-                <para><emphasis><methodname>extension</methodname></emphasis></para>
+          <para>Uses the specified password when logging the user in with the
+          username specified with <methodname>--user</methodname>.</para>
+        </sect2>
 
-                <para>The extension type to append to the file name.</para>
-              </listitem>
-            </itemizedlist>
+        <sect2>
+          <title>Persistor</title>
 
-            <para>An example configuration would be:-</para>
+          <screen format="linespecific">-r &lt;persistor&gt;
+--persistor &lt;persistor&gt;</screen>
 
-            <programlisting format="linespecific">isis.snapshotserver.port=12345
-isis.snapshotserver.directory=logs
-isis.snapshotserver.filename=log
-isis.snapshotserver.extension=xml</programlisting>
-          </sect3>
+          <para>Ignored if type is client.</para>
 
-          <sect3>
-            <title>Web snapshot appender</title>
+          <para>The persistor option allows you to choose how the objects
+          created by the system will be persisted so they are still available
+          the next time you run the system. The following options are
+          available with the current distribution, and if none is specified
+          then the in-memory persistor will be used for exploration mode and
+          xml persistor will be used for other non-client modes by
+          default.</para>
 
-            <para>The <classname>WebSnapshotAppender</classname> sends the
-            snapshot to a web server. The following properties can be
-            specified:-</para>
+          <para><emphasis>in-memory</emphasis> - A simple non-persisting
+          mechanism that will only hold the persisted object while the virtual
+          machine is running. This is used for testing and
+          demonstrating.</para>
 
-            <itemizedlist>
-              <listitem>
-                <para><emphasis><methodname>url</methodname></emphasis></para>
+          <para><emphasis>xml</emphasis> - A simple file based mechanism that
+          encodes each object's data in an XML file. Alongside the data files
+          for the objects are instance lists listing all the files for each
+          type of object.<emphasis></emphasis></para>
 
-                <para>URL of server to post data to (including the protocol
-                'http').</para>
-              </listitem>
+          <para><emphasis>&lt;class name&gt;</emphasis> - By specifying a
+          class name the boot loader will load up that class as the
+          persistor.</para>
+        </sect2>
 
-              <listitem>
-                <para><emphasis><methodname>proxyAddress</methodname></emphasis></para>
+        <sect2>
+          <title>Remote connector</title>
 
-                <para>Address of web proxy if one is being used.</para>
-              </listitem>
+          <screen format="linespecific">-x &lt;connector&gt;
+--connector &lt;connector&gt;</screen>
 
-              <listitem>
-                <para><emphasis><methodname>proxyPort</methodname></emphasis></para>
+          <para>Ignored if mode is not a client. If the type is a client then
+          a connection mechanism can be specified. Connector mechanisms
+          available are:-</para>
 
-                <para>Port of proxy server.</para>
-              </listitem>
-            </itemizedlist>
+          <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
+          mechanism (of value types) to serialize/deserialize objects, over
+          TCP/IP sockets.</para>
 
-            <para>The following example sends a default length snapshot to the
-            webserver.</para>
+          <para><emphasis>encoding-http</emphasis> - Uses the encoding

[... 289 lines stripped ...]


Mime
View raw message