You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2014/02/12 00:31:09 UTC
[12/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml b/mothballed/docbkx/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
new file mode 100644
index 0000000..a924ac6
--- /dev/null
+++ b/mothballed/docbkx/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
@@ -0,0 +1,2752 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<book>
+ <bookinfo>
+ <title><?eval ${docbkxGuideTitle}?></title>
+
+ <subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
+ <releaseinfo><?eval ${project.version}?></releaseinfo>
+
+ <authorgroup>
+ <author>
+ <firstname>Dan</firstname>
+
+ <surname>Haywood</surname>
+ </author>
+ </authorgroup>
+
+ <legalnotice>
+ <para>Permission is granted to make and distribute verbatim copies of
+ this manual provided that the copyright notice and this permission
+ notice are preserved on all copies.</para>
+ </legalnotice>
+ </bookinfo>
+
+ <!-- front matter -->
+
+ <toc></toc>
+
+ <preface id="preface">
+ <title>Preface</title>
+
+ <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 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>The role of the runtime component within <emphasis>Isis</emphasis>
+ is to bootstrap the application and components, and to manage the
+ lifecycle of domain object entities. Typically, this means managing their
+ persistence and identity.</para>
+
+ <para>The runtime component within Isis is also pluggable. This guide
+ describes the <emphasis>default runtime</emphasis> implementation, which
+ consists of a number of a parent module
+ <package>[oai.runtimes:dflt]</package> and a number of child submodules.
+ These submodules allow the behaviour of the default runtime to be
+ customized, most notably to to support different objectstores. The
+ <emphasis>default runtime</emphasis> also supports a number of other
+ capabilities, such as client/server remoting and the concept of
+ profilestores.</para>
+
+ <sect1>
+ <title>Who this Guide is For</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 two parts:<itemizedlist>
+ <listitem>
+ <para>Users' Guide (<xref linkend="prt.UsersGuide" />)</para>
+
+ <para>The chapters in this part of the guide are written for the
+ developer who wants to just use the <emphasis>default
+ runtime</emphasis> in their own domain applications. It describe
+ how to run applications that use the <emphasis>default
+ runtime</emphasis> in the development environment, how to
+ configure the <emphasis>default runtime</emphasis>, and how to
+ deploy applications in the various different ways using the
+ <emphasis>default runtime</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Contributors' Guide (<xref
+ linkend="prt.ContributorsGuide" />)</para>
+
+ <para>The chapters in this part of the guide are written for those
+ Isis contributors who want to enhance, improve or otherwise change
+ the <emphasis>default runtime</emphasis> itself They describe the
+ core concepts underpinning the design of the <emphasis>default
+ runtime</emphasis>, and provide a walk through of each of the
+ modules that make up the <emphasis>default
+ runtime</emphasis>.</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>How this Guide relates to other Documentation</title>
+
+ <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
+ <emphasis>default runtime</emphasis>, 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>
+
+ <part id="prt.UsersGuide">
+ <title>Users Guide</title>
+
+ <partintro>
+ <para>This part of the guide is written for developers who wish to run
+ their own Isis domain applications using the <emphasis>default
+ runtime</emphasis>, and wish to configure the default runtime for their
+ own particular application.</para>
+
+ <para>The chapters are organized as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>getting started (in the development environment)</para>
+
+ <para>how to run an <emphasis>Isis</emphasis> application using the
+ default runtime within the development environment</para>
+ </listitem>
+
+ <listitem>
+ <para>deploying as a webapp</para>
+
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a web application (using one of the
+ <emphasis>Isis</emphasis> web viewers)</para>
+ </listitem>
+
+ <listitem>
+ <para>deploying in standalone mode</para>
+
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a standalone application (using the DnD viewer or
+ similar)</para>
+ </listitem>
+
+ <listitem>
+ <para>deploying in client/server mode</para>
+
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a client/server application (using the DnD viewer or
+ similar for the client, and another instance of the application
+ running as the server)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title>Getting Started</title>
+
+ <para>This chapter assumes that you have an application that has been
+ generated using the Maven quickstart archetype. This archetype generates
+ an application that is preconfigured to run using the <emphasis>default
+ runtime</emphasis>, so some of what is documented here will already have
+ been set up.</para>
+
+ <sect1 id="sec.RuntimeLauncher">
+ <title>Launching <classname>Isis</classname></title>
+
+ <para>The <emphasis>default runtime</emphasis> provides several
+ different mechanisms by which to launch an <emphasis>Apache
+ Isis</emphasis> application.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the first is the <classname>org.apache.isis.Isis</classname>
+ command line runner.</para>
+
+ <para>This allows Isis to be run from the command line, with the
+ <acronym>UI</acronym> to use being specified by the
+ <code>--viewer</code> flag.</para>
+ </listitem>
+
+ <listitem>
+ <para>the second is the
+ <classname>org.apache.isis.WebServer</classname> webapp
+ runner.</para>
+
+ <para>This is intended to be used only with Maven modules that are
+ structured as a webapp; specifically, with a
+ <filename>src/main/webapp/WEB-INF/web.xml</filename> file.</para>
+
+ <para>The <classname>WebServer</classname> class is completely
+ generic, so in principle this <filename>web.xml</filename> could
+ contain any servlets etc. To use <emphasis>Isis</emphasis>,
+ though, it will typically contain the
+ <classname>oai.runtimes.dflt.webapp.IsisWebAppBootstrapper</classname>
+ (a <classname>javax.servlet.ServletContextListener</classname>),
+ along with the
+ <classname>oai.runtimes.dflt.webapp.IsisSessionFilter</classname>
+ (<classname>a javax.servlet.Filter</classname>)<footnote>
+ <para>We say "typically"; however some of the web-based
+ viewers have their own, equivalent, mechanisms. For example,
+ the <emphasis>Wicket viewer</emphasis>
+ <package>[oai.viewer:wicket]</package> provides a custom
+ subclass of the org.apache.wicket.Application for
+ bootstrapping, while the two RESTful viewers (<emphasis>JSON
+ viewer</emphasis> and <emphasis>XHTML viewer</emphasis>) are
+ bootstrapped using the
+ <classname>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</classname>,
+ providing a custom subclass of
+ <classname>javax.ws.rs.core.Application</classname> to
+ register with Resteasy.</para>
+ </footnote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>the third option also applies only for webapps, and is
+ simply to run using your IDE's built-in support for hosting
+ webapps. For example, if using Eclipse then this is the <ulink
+ url="http://eclipse.org/webtools">Eclipse WTP</ulink>
+ support.</para>
+ </listitem>
+
+ <listitem>
+ <para>and the final option is similar, and also applies only to
+ webapps, namely to run the webapp from Maven using <code>mvn
+ jetty:run</code> plugin.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Both <classname>org.apache.isis.Isis</classname> and
+ <classname>org.apache.isis.WebServer</classname> classes have main()
+ methods meaning that they are run from the command line. If you have
+ run the archetype then you'll find that there are Eclipse IDE launch
+ configurations for both <classname>oai.Isis</classname> and
+ <classname>oai.WebRunner</classname> (in the
+ <filename>ide/eclipse/launch</filename> directories).</para>
+
+ <para>These two runners act as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>start up the logging so that log messages are never
+ lost;</para>
+ </listitem>
+
+ <listitem>
+ <para>load up all the installers (component factories) that can be
+ found on the classpath from the
+ <filename>installer-registry.properties</filename> file.
+ (Physically this is packaged within the
+ [oai.core:isis-core-runtime] module's
+ <acronym>JAR</acronym>).</para>
+
+ <para>This allow the runner class to be aware of all the
+ components that are available;</para>
+ </listitem>
+
+ <listitem>
+ <para>parse the command line flags;</para>
+
+ <para>If there is problem with these then a help text is displayed
+ list all the options and the program exits</para>
+ </listitem>
+
+ <listitem>
+ <para>with the command line flags processed, initialize the
+ installers and bootstraps the system.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The next section lists the command line flags supported by these
+ two runners.</para>
+ </sect1>
+
+ <sect1>
+ <title>Command Line Flags</title>
+
+ <para>The following table summarises the command line-flags common to
+ both <classname>org.apache.isis.Isis</classname> commandline runner as
+ well as the <classname>org.apache.isis.WebServer</classname> webapp
+ runner utility.</para>
+
+ <note>
+ <para>Internally, all options are handled by subclasses of the
+ <classname>oai.core.runtime.optionhandler.OptionHandler</classname>
+ interface.</para>
+ </note>
+
+ <para><table>
+ <title>Common command line flags</title>
+
+ <tgroup cols="6">
+ <colspec align="center" />
+
+ <colspec colwidth="10%" />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
+
+ <entry align="center">Long form</entry>
+
+ <entry align="center">Purpose</entry>
+
+ <entry align="center">Typical values</entry>
+
+ <entry align="center">Default value</entry>
+
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>-t <emphasis>deploymenttype</emphasis></entry>
+
+ <entry>--type</entry>
+
+ <entry>The deployment mode; influences other settings and
+ defaults.</entry>
+
+ <entry><emphasis>exploration</emphasis>,
+ <emphasis>prototype</emphasis>, <emphasis>client,
+ singleuser, server_exploration, server_prototype, server,
+ utilty</emphasis></entry>
+
+ <entry><emphasis>prototype</emphasis></entry>
+
+ <entry>Value corresponds to lower case form of
+ <classname>DeploymentType</classname> class. If running
+ under <classname>WebServer</classname>, should only use
+ <emphasis>server_xxx</emphasis> values. Some viewers (eg the
+ wicket viewer) may define additional deployment
+ types.</entry>
+ </row>
+
+ <row>
+ <entry>-v <emphasis>viewername</emphasis></entry>
+
+ <entry>--viewer</entry>
+
+ <entry>Specifies the user interface (viewer
+ implementation).</entry>
+
+ <entry><emphasis>dnd</emphasis>, <emphasis>html</emphasis>,
+ <emphasis>restful</emphasis>, or FQCN that implements
+ <classname>ViewerInstaller</classname>. can also specify
+ <emphasis>encoding-http, encoding-sockets,
+ serializing-sockets, xstream-sockets</emphasis></entry>
+
+ <entry><emphasis>dnd</emphasis></entry>
+
+ <entry><para>Values are taken from
+ <filename>installer-registry.properties</filename>. See also
+ <xref
+ linkend="sec.ClientConnectorVsViewer" /></para></entry>
+ </row>
+
+ <row>
+ <entry>-r <emphasis>persistorname</emphasis></entry>
+
+ <entry>--persistor</entry>
+
+ <entry>The persistence mechanism (ie object store
+ implementation) to use for persisting domain objects between
+ runs.</entry>
+
+ <entry><emphasis>in-memory, xml, sql, nosql, fileserver,
+ mongodb</emphasis>, or FQCN that implements
+ <classname>PersistenceMechanismInstaller</classname>.</entry>
+
+ <entry>depends upon the deployment type, eg is
+ <emphasis>in-memory</emphasis> for
+ <emphasis>exploration</emphasis>, or
+ <emphasis>xml</emphasis> if
+ <emphasis>server</emphasis>.</entry>
+
+ <entry>Ignored if deployment type is
+ <emphasis>client</emphasis>. Values are taken from
+ <filename>installer-registry.properties</filename></entry>
+ </row>
+
+ <row>
+ <entry>-e <emphasis>profilestorename</emphasis></entry>
+
+ <entry>--user-profile-store</entry>
+
+ <entry>The profile store implementation to use for
+ persisting user profile data between runs.</entry>
+
+ <entry><emphasis>in-memory, xml</emphasis>, or FQCN that
+ implements
+ <classname>UserProfileStoreInstaller</classname>.</entry>
+
+ <entry>depends upon the deployment type, eg is
+ <emphasis>in-memory</emphasis> for
+ <emphasis>exploration</emphasis>, or
+ <emphasis>xml</emphasis> if
+ <emphasis>server</emphasis>.</entry>
+
+ <entry>Values are taken from
+ <filename>installer-registry.properties</filename></entry>
+ </row>
+
+ <row>
+ <entry>-x <emphasis>connectorname</emphasis></entry>
+
+ <entry>--connector</entry>
+
+ <entry>The protocol to use for a client when deploying
+ client/server.</entry>
+
+ <entry><emphasis>encoding-http, encoding-sockets,
+ serializing-sockets, xstream-sockets</emphasis>, or FQCN
+ that implements
+ <classname>ClientConnectionInstaller</classname>.</entry>
+
+ <entry></entry>
+
+ <entry>Ignored if deployment type is not
+ <emphasis>client</emphasis>. Values are taken from
+ <filename>installer-registry.properties</filename>. See also
+ <xref linkend="sec.ClientConnectorVsViewer" /></entry>
+ </row>
+
+ <row>
+ <entry>-f <emphasis>fixturename</emphasis></entry>
+
+ <entry>--fixture</entry>
+
+ <entry>Specify fixtures to load (rather than read from
+ configuration file)</entry>
+
+ <entry>FQCN that implements
+ <classname>InstallableFixture</classname>.</entry>
+
+ <entry></entry>
+
+ <entry>Ignored if deployment type is not
+ <emphasis>exploration, prototype,
+ server_exploration</emphasis> or
+ <emphasis>server_prototype</emphasis>. If has been
+ specified, any fixtures in the configuration file is
+ ignored.</entry>
+ </row>
+
+ <row>
+ <entry>-c <emphasis>filename</emphasis></entry>
+
+ <entry>--config</entry>
+
+ <entry>Loads in the specified configuration file.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>The file is loaded in addition to <filename
+ class="directory" moreinfo="none">isis.properties</filename>
+ and the properties files relating to the installed
+ component.</entry>
+ </row>
+
+ <row>
+ <entry>-D <emphasis>property=value</emphasis></entry>
+
+ <entry></entry>
+
+ <entry>Specify additional configuration properties.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>Multiple -D flags can be specified.</entry>
+ </row>
+
+ <row>
+ <entry>-s</entry>
+
+ <entry>--nosplash</entry>
+
+ <entry>Do not show the splash screen</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-quiet</entry>
+
+ <entry></entry>
+
+ <entry>Configure logging to log ERRORs only</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
+
+ <row>
+ <entry>-verbose</entry>
+
+ <entry></entry>
+
+ <entry>Configure logging to log INFO, WARN and
+ ERRORs.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
+
+ <row>
+ <entry>-debug</entry>
+
+ <entry></entry>
+
+ <entry>Configure logging to log DEBUG, INFO, WARN and
+ ERRORs.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
+
+ <row>
+ <entry>-diagnostics</entry>
+
+ <entry></entry>
+
+ <entry>print information that can be used to report or
+ diagnose problems</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-version</entry>
+
+ <entry></entry>
+
+ <entry>Print the version of the framework.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-h</entry>
+
+ <entry>--help</entry>
+
+ <entry>Print out usage</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>Only the components that can be used are
+ listed.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <para>The --type (deployment type) is discussed in more detail in
+ <xref linkend="sec.DeploymentType" />.</para>
+
+ <para>In addition, the <classname>org.apache.isis.Isis</classname>
+ commandline runner has a couple command flags specific to it:</para>
+
+ <table>
+ <title><classname>org.apache.isis.Isis</classname> additional
+ command line flags</title>
+
+ <tgroup cols="6">
+ <colspec align="center" />
+
+ <colspec colwidth="10%" />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
+
+ <entry align="center">Long form</entry>
+
+ <entry align="center">Purpose</entry>
+
+ <entry align="center">Typical values</entry>
+
+ <entry align="center">Default value</entry>
+
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>-u <emphasis>username</emphasis></entry>
+
+ <entry>--user</entry>
+
+ <entry>Uses the specified name when logging the user in
+ (provided that --password also specified).</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>Ignored if deployment type is not
+ <emphasis>exploration</emphasis>,
+ <emphasis>prototype</emphasis>,
+ <emphasis>server_exploration</emphasis> or
+ <emphasis>server_prototype</emphasis>.</entry>
+ </row>
+
+ <row>
+ <entry>-p <emphasis>password</emphasis></entry>
+
+ <entry>--password</entry>
+
+ <entry>Specifies password for --username.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The username/password should be valid as per the configured
+ authentication mechanism. For example, if using the file
+ authentication mechanism, then the user/password should reside in the
+ <filename>security_file.password</filename> configuration file.</para>
+
+ <para>The <classname>org.apache.isis.WebServer</classname> webapp
+ runner also has a couple command flags specific to it:</para>
+
+ <table>
+ <title><classname>org.apache.isis.WebRunner</classname> additional
+ command line flags</title>
+
+ <tgroup cols="6">
+ <colspec align="center" />
+
+ <colspec colwidth="10%" />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <colspec />
+
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
+
+ <entry align="center">Long form</entry>
+
+ <entry align="center">Purpose</entry>
+
+ <entry align="center">Typical values</entry>
+
+ <entry align="center">Default value</entry>
+
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>-a <emphasis>address</emphasis></entry>
+
+ <entry>--address</entry>
+
+ <entry>Address to listen on</entry>
+
+ <entry></entry>
+
+ <entry>localhost</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-p <emphasis>portnumber</emphasis></entry>
+
+ <entry>--port</entry>
+
+ <entry>Specifies password for --username.</entry>
+
+ <entry></entry>
+
+ <entry>8080</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-w <emphasis>resourseBase</emphasis></entry>
+
+ <entry>--webapp</entry>
+
+ <entry>The location of the webapp relative to
+ <filename>src/main/webapp</filename>.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>Usually left at its default, "".</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The --type (deployment type) option influences the defaults for
+ other options, so warrants a little more detail.</para>
+
+ <sect2 id="sec.DeploymentType">
+ <title>Deployment Type</title>
+
+ <para>The deployment type defines the "mode" in which Isis is
+ running. The values correspond to the instances of DeploymentType,
+ and so will always include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>exploration</emphasis></para>
+
+ <para>Exploration mode is for developers to explore and test
+ their code, with a number of features all designed to reduce the
+ length of the feedback loop. This is covered in more detail in
+ <xref linkend="sec.ExplorationAndPrototypeModes" />.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>prototype</emphasis></para>
+
+ <para>The intention of prototype mode is to make the system easy
+ to demonstrate in realistic fashion, without necessarily having
+ to go through the rigamarole of building and deploying the
+ system . It has some similarities to exploration mode, so is
+ also covered in more detail in <xref
+ linkend="sec.ExplorationAndPrototypeModes" />.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>single-user</emphasis></para>
+
+ <para>The single user mode is for an application that is
+ intended to run a single user, with the DnD viewer (or
+ equivalent), and with the application performing its own object
+ persistence. An example might be a mail application, or a ToDo
+ manager.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>client</emphasis></para>
+
+ <para>Client mode is intended for client/server deployments,
+ where each user runs the application locally (with the DnD
+ viewer or equivalent), connecting to another instance of Isis
+ running as a server somewhere else on the network. With this
+ mode selected the (<emphasis>-x connectorname</emphasis> flag)
+ must also be specified.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server</emphasis></para>
+
+ <para>Server mode is intended for Isis running in multi-threaded
+ mode, concurrently servicing multiple clients. Usually this
+ means Isis being deployed as a webapp using one of the web
+ viewers (HTML viewer, Scimpi, Restful, Wicket etc), but it could
+ also be running as a server for a client/server remoting
+ application.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server-exploration</emphasis></para>
+
+ <para>The server-exploration mode is similar to server mode, but
+ with exploration features enabled. See <xref
+ linkend="sec.ExplorationAndPrototypeModes" /> for more detail on
+ exploration mode.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server-prototype</emphasis></para>
+
+ <para>The server-prototype mode is similar to server mode, but
+ with prototyping features enabled. See <xref
+ linkend="sec.ExplorationAndPrototypeModes" /> for more detail on
+ prototype mode.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If no mode is specified, the framework will start up in
+ <emphasis>prototype</emphasis> mode.</para>
+ </sect2>
+
+ <sect2 id="sec.ClientConnectorVsViewer">
+ <title>Relationship between Client Connectors and Viewers</title>
+
+ <para>You may have noticed that some of the same values can be
+ specified for --viewer and for --connector. Specifically, these
+ common values are: <emphasis>encoding-sockets, encoding-http,
+ serializing-sockets</emphasis>, and
+ <emphasis>xstream-sockets</emphasis>.</para>
+
+ <para>When specified as a client connector using --connector (and
+ provided that the deployment type is client), then Isis is
+ configured to run as a client in a client/server remoting
+ deployment. In this deployment mode there is no persistor/object
+ store configured, instead all requests are sent across the wire to
+ be invoked on a server. The values are used to select an
+ implementation of <classname>ClientConnectionInstaller</classname>
+ which is configured in
+ <filename>installer-registry.properties</filename><footnote>
+ <para>If you look at the source code, you'll see that
+ <classname>ClientConnectionInstaller</classname> is actually a
+ subclass of
+ <classname>PersistenceMechanismInstaller</classname>. So, in
+ fact, there <emphasis>is</emphasis> a persistence mechanism, it
+ just happens to be one that is a proxy to a network connection
+ with a server.</para>
+ </footnote>.</para>
+
+ <para>When these values are specified as a viewer using --viewer
+ (and provided that the deployment type is server), then Isis is
+ configured to run as the corresponding server. The "viewer" in this
+ case is a network listener that receives the requests from the
+ client, unmarshals them, and invokes them on the same domain objects
+ within the server.</para>
+
+ <para>The name of these client connectors/viewers xxx-yyy is a
+ concatenation both the marshalling mechanism (xxx) and underlying
+ transport (yyy):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
+ mechanism (of value types) to serialize/deserialize objects,
+ over TCP/IP sockets.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>encoding-http</emphasis> - Uses the encoding
+ mechanism (of value types) to serialize/deserialize objects,
+ over HTTP.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>serializing-sockets</emphasis> - Uses Java
+ serialization (of value types) to serialize/deserialize objects,
+ over TCP/IP sockets.</para>
+ </listitem>
+
+ <listitem>
+ <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>
+ </listitem>
+ </itemizedlist>
+
+ <para>One final remark: the <emphasis>encoding-http</emphasis>
+ viewer can only be run as a webapp; see <xref
+ linkend="sec.WebAppDeployment" /> for more details on how deploying
+ this option.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Configuration Files</title>
+
+ <para>During start-up <emphasis>Isis</emphasis> 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. Then, dependent upon the
+ components that are specified, it will also search for other
+ configuration files. (These files do not need to be present for the
+ framework to start up).</para>
+
+ <para>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'. So 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>The location of the configuration files depends on the runner.
+ All runners will load from the classpath (eg in
+ <filename>src/main/resources</filename>). Webapp viewers will also
+ load from <filename>WEB-INF</filename> directory
+ (<filename>src/main/webapp/WEB-INF</filename>).</para>
+
+ <para>Usually the <filename>isis.properties</filename> file will be
+ quite small, because most of the component-specific configuration will
+ be in their own config files. However, two important keys will almost
+ always be present: services, and fixtures.</para>
+
+ <sect2>
+ <title>Services</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+
+ <sect2 id="sec.LoginFixture">
+ <title>Fixtures</title>
+
+ <para>Depending upon the</para>
+
+ <para>*** todo</para>
+
+ <para></para>
+
+ <para>*** discuss login fixtures.</para>
+
+ <para></para>
+
+ <para></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec.ExplorationAndPrototypeModes">
+ <title>Exploration and Prototype Modes</title>
+
+ <para></para>
+
+ <para>The intention of exploration mode is for developers to explore
+ and test their code, with a number of features all designed to reduce
+ the length of the feedback loop.</para>
+
+ <para></para>
+
+ <para>It enables a number of options and removes the requirement to
+ login</para>
+
+ <para>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'.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>It is an error to specify a persistor type in exploration
+ mode.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para><classname>LoginFixture</classname> is present, see <xref
+ linkend="sec.LoginFixture" />).</para>
+
+ <para></para>
+
+ <para>Server mode, but if a <classname>LoginFixture</classname> is
+ present then all clients will automatically be logged in as this
+ user.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>The intention of prototype mode is to make the system easy to
+ demonstrate in realistic fashion, without necessarily having to go
+ through the rigamarole of building and deploying the system . There
+ has some similarities to exploration mode, so is covered also in <xref
+ linkend="sec.ExplorationAndPrototypeModes" /></para>
+
+ <para>similar to exploration mode</para>
+
+ <para>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></para>
+
+ <para>*** discuss the shaded JARs from the Maven plugin.</para>
+
+ <para></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"
+ will be used and switching between users will not be possible.</para>
+
+ <programlisting format="linespecific">isis.exploration.users=sven, dick, bob</programlisting>
+
+ <para>To disable the showing of exploration menu items set the
+ following property to false (by default exploration options are
+ shown).</para>
+
+ <programlisting format="linespecific">isis.exploration.show=false</programlisting>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Standalone Deployment</title>
+
+ <para></para>
+
+ <note>
+ <para>TODO: discuss sealed/signed JARs to prevent tampering?</para>
+ </note>
+
+ <para></para>
+
+ <sect1>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Client/Server Deployment</title>
+
+ <para></para>
+
+ <para>*** defer encoding-http to next chapter.</para>
+
+ <para></para>
+
+ <section>
+ <title></title>
+
+ <para></para>
+
+ <para></para>
+ </section>
+ </chapter>
+
+ <chapter id="sec.WebAppDeployment">
+ <title>Web App Deployment</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>Setting up Security</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Building a Regular Webapp</title>
+
+ <para></para>
+
+ <para>The final mechanism is to use Maven to package up the webapp
+ project as a WAR file, packaging up whatever is in the web.xml file.
+ As above, ordinarily the web.xml will be configured to run the same
+ HTML viewer, so the end result will be the same. However, if necessary
+ the remoting servlet can also be configured</para>
+
+ <para>Packaging up is done using:</para>
+
+ <screen format="linespecific">$ cd viewer-xxx
+$ mvn clean package</screen>
+
+ <para>where viewer-xxx is the module containing the WEB-INF.</para>
+
+ <para></para>
+
+ <para>This should result in a WAR file in <filename>target</filename>
+ directory. This can be deployed to an existing servlet
+ containerd</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Deploying Client/Server (with encoding-http)</title>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+ </part>
+
+ <part id="prt.ContributorsGuide">
+ <title>Contributors Guide</title>
+
+ <partintro>
+ <para>The part of the guide is written for <emphasis>Isis</emphasis>
+ contributors who wish to understand the implementation of the default
+ runtime in order to enhance/improve/fix it.</para>
+
+ <para>The chapters in this part of the guide:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>outlines the core concepts within the <emphasis>default
+ runtime</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>describe the purpose and major classes of each of the default
+ runtime modules.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title>Core Concepts</title>
+
+ <abstract>
+ <para>The core concepts that make up the default runtime
+ implementation.</para>
+ </abstract>
+
+ <para>The role of the runtime component within <emphasis>Isis</emphasis>
+ is to bootstrap the application and components, and to manage the
+ lifecycle of domain object entities. Typically, this means managing
+ their persistence and identity. The default runtime implementation
+ <package>[oai.runtimes:dflt]</package> provides support for this, and
+ additionally provides support for client/server remoting and also the
+ concept of a profilestore.</para>
+
+ <para>Because the scope of the <emphasis>default runtime</emphasis>
+ includes remoting, it necessarily adds a degree of abstraction that,
+ perhaps, might not otherwise be required. This chapter explains the main
+ concepts defined or implemented by the <emphasis>default
+ runtime</emphasis>.</para>
+
+ <para>This chapter should help you understand better how the default
+ runtime works. If you just want to use the</para>
+
+ <sect1>
+ <title>Components of the Core Runtime</title>
+
+ <para>As will be clear if you've explored the codebase, the
+ <emphasis>core runtime</emphasis> implementation consists of a main
+ <emphasis>runtime</emphasis>
+ module<package>[oai.core:runtime]</package> along with a
+ fairly large number of components.</para>
+
+ <para>The main <emphasis>runtime</emphasis> module provides the
+ following functionality:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>classes to bootstrap the core runtime</para>
+ </listitem>
+
+ <listitem>
+ <para>the "installer" registry; a repository of components that
+ can be bootstrapped</para>
+ </listitem>
+
+ <listitem>
+ <para>implementations of the
+ <classname>AuthenticationManager</classname> and
+ <classname>AuthorizationFacetFactory</classname> interfaces for
+ the default runtime</para>
+ </listitem>
+
+ <listitem>
+ <para>an abstract <classname>PersistenceSession</classname>
+ <acronym>API</acronym> that provides a very generalized means for
+ managing the lifecycle of domain objects</para>
+
+ <para>This includes an <classname>ObjectFactory</classname> API
+ which (in conjunction with the
+ <classname>ClassSubstitor</classname> interface defined in the
+ <package>[oai.core:metamodel]</package> module) provides hook-in
+ points for bytecode enhancement libraries (discussed further
+ below);</para>
+ </listitem>
+
+ <listitem>
+ <para>an implementation of the
+ <classname>PersistenceSession</classname> <acronym>API</acronym>
+ which does some of the common work for persistence management and
+ defines its own object store <acronym>API</acronym></para>
+ </listitem>
+
+ <listitem>
+ <para>a mechanism to define the set of application domain services
+ to make available to the domain objects</para>
+ </listitem>
+
+ <listitem>
+ <para>a mechanism to define the set of fixtures to automatically
+ install into the object store (for use when testing or
+ prototyping)</para>
+ </listitem>
+
+ <listitem>
+ <para>a mechanism (<classname>Memento</classname>) for capturing
+ the state of domain objects over time</para>
+ </listitem>
+
+ <listitem>
+ <para>support for more easily building <acronym>XML</acronym>
+ snapshots (using the
+ <classname>oai.applib.snapshot.Snapshottable</classname>
+ interface)</para>
+ </listitem>
+
+ <listitem>
+ <para>a means of storing user preference / profile information
+ (including, for example, bookmarks to objects).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The rest of the <emphasis>default runtime</emphasis>
+ (sub)modules provide implementations of the major
+ <acronym>API</acronym>s that the <emphasis>default runtime</emphasis>
+ exposes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>object store</para>
+
+ <para>The object store <acronym>API</acronym> defines a
+ persistence mechanism for storing domain objects. Examples include
+ a simple in-memory object store (useful only for prototyping), an
+ <acronym>XML</acronym> objectstore, a simple
+ <acronym>SQL</acronym> objectstore, and a "NoSQL" (JSON-based)
+ objectstore.</para>
+ </listitem>
+
+ <listitem>
+ <para>bytecode enhancement</para>
+
+ <para>Bytecode enhancement classes provide the ability to support
+ lazy loading while walking a graph from one domain object to
+ another, using tools such as <ulink
+ url="http://cglib.sourceforge.net">cglib</ulink> or <ulink
+ url="http://www.javassist.org">javassist</ulink>. This is a
+ similar technique to that employed by <acronym>ORM</acronym>s, but
+ is available even if the object store involved does not support
+ lazy loading.<footnote>
+ <para>Indeed, ORM-based object stores (are likely to) require
+ the bytecode providers to be disabled.</para>
+ </footnote></para>
+
+ <para>The bytecode enhancement is also used for automatic tracking
+ of dirty objects (so that Isis knows to flush them to the object
+ store at the end of the transaction). The primary
+ <acronym>API</acronym> that supports bytecode enhancement is
+ <classname>ObjectFactory</classname>, discussed in <xref
+ linkend="sec.SessionLevelScope" />.</para>
+ </listitem>
+
+ <listitem>
+ <para>profile store</para>
+
+ <para>The profile store <acronym>API</acronym> defines a
+ persistence mechanism for storing user profile information.
+ Examples include a simple in-memory profile store (useful only for
+ prototyping and testing), and an <acronym>XML</acronym>
+ profilestore.</para>
+ </listitem>
+
+ <listitem>
+ <para>client/server remoting support</para>
+
+ <para>The <emphasis>default runtime</emphasis> also provides
+ support for client/server remoting, through an alternative
+ implementation of the <classname>PersistenceSession</classname>
+ <acronym>API</acronym><footnote>
+ <para>Alternative, that is, to the
+ <classname>PersistenceSession</classname> implementation for
+ object stores.</para>
+ </footnote>.</para>
+
+ <para>For example, the DnD viewer can be configured to act as a
+ client, holding a cache of domain objects client-side.
+ Interactions with these domain objects are sent transparently
+ across to a server running the same application domain classes;
+ the changes are performed server-side and the results sent back
+ down to the client where the results are merged.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, because many of the <emphasis>Isis</emphasis>
+ viewers are webapps, the <emphasis>default runtime</emphasis> also
+ has:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>a module <package>[oai.core:isis-core-runtime]</package> with
+ <classname>ServletContextListener</classname> and
+ <classname>javax.servlet.Filter</classname> implementations to
+ allow <emphasis>Isis</emphasis> to be bootstrapped from a
+ webapp</para>
+ </listitem>
+
+ <listitem>
+ <para>provides a convenience module
+ <package>[oai.core:isis-core-webserver]</package> that provides a
+ command-line utility to allow any Maven webapp-structured project
+ to be hosted within Jetty.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="sec.InstallerLookup">
+ <title><classname>InstallerLookup</classname> and
+ <filename>installer-registry.properties</filename></title>
+
+ <para>The <emphasis>Isis</emphasis> core modules
+ <package>[oai:core]</package> already provide the
+ <classname>oai.core.commons.components.Installer</classname> interface
+ which defines a factory interface for any component within
+ <emphasis>Isis</emphasis>.</para>
+
+ <para>The <emphasis>default runtime</emphasis> builds upon this
+ infrastructure by providing the <classname>InstallerLookup</classname>
+ interface (in
+ <package>oai.runtimes.dflt.runtime.installerregistry</package>) to act
+ as a registry of all available <classname>Installer</classname>s that
+ have been bootstrapped. It also provides an implementation,
+ <classname>InstallerLookupDefault</classname>, which looks up the
+ implementations from the
+ <filename>installer-registry.properties</filename> file. This registry
+ file can be found in <package>oai.runtimes.dflt.runtime</package>
+ package. If no implementation is specified, then a default (defined in
+ <package>oai.runtimes.dflt.runtime.system.SystemConstants</package>)
+ is used. For some components the specified
+ <classname>DeploymentType</classname> will cause the default to vary;
+ for example, the default persistence mechanism when running in
+ exploration mode is to use the in-memory object store; otherwise
+ though the XML object store is defaulted.</para>
+
+ <para>In addition to loading components, the
+ <classname>InstallerLookupDefault</classname> also updates the
+ (mutable) <classname>IsisConfigurationBuilder</classname>, from which
+ an <classname>IsisConfiguration</classname> is snapshotted. It does
+ this by asking each <classname>Installer</classname> for its
+ configuration files
+ (<methodname>Installer#getConfigurationResources()</methodname>). For
+ those installers that inherit from
+ <classname>oai.core.commons.config.InstallerAbstract</classname> (ie
+ most if not all of them), this returns a collection of two file names
+ that follow the convention:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>type.properties</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>type_name.properties</filename></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For example, if loading the XML persistence mechanism/object
+ store this will search for <filename>persistor.properties</filename>
+ and then <filename>persistor_xml.properties</filename>.</para>
+
+ <para>It's worth pointing out that
+ <classname>InstallerLookupDefault</classname> is, in turn, defaulted
+ from <classname>IsisModule</classname>. This is an implementation if a
+ <classname>com.google.inject.Module</classname>, meaning that
+ <emphasis>Isis</emphasis> is, in fact, ultimately bootstrapped by
+ <ulink url="http://code.google.com/p/google-guice/">Google
+ Guice</ulink><footnote>
+ <para>At least, when the <emphasis>default runtime</emphasis> is
+ used.</para>
+ </footnote>.</para>
+ </sect1>
+
+ <sect1>
+ <title>Component Scopes</title>
+
+ <para>The components loaded by <classname>InstallerLookup</classname>
+ are thread-safe singletons with application (global) scope. From them
+ the <emphasis>Isis</emphasis> runtime instantiates further components
+ at session, and within that transaction-level scope. This is shown
+ below:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/architecture.png" scale="45" />
+ </imageobject>
+ </mediaobject>
+
+ <para>For webapp-based viewers, an <classname>IsisSession</classname>
+ is instantiated at the beginning of the HTTP request, and is
+ automatically closed at the end of the request. In this regard it is
+ very similar to the concept of a <acronym>JPA
+ </acronym><classname>javax.persistence.PersistenceContext</classname>
+ or <ulink url="http://hibernate.org">Hibernate</ulink>
+ <classname>org.hibernate.Session</classname>.</para>
+
+ <para>For client/server deployments, an
+ <classname>IsisSession</classname> is similar for the server, but for
+ the client an <classname>IsisSession</classname> is started when the
+ user starts the client, and is only closed when the user quits
+ out.<footnote>
+ <para>There are, arguably, some issues with this design. In the
+ future we may deprecate this design in favour of a design of
+ client that is wholly stateless.</para>
+ </footnote></para>
+
+ <para>As the diagram illustrates, an
+ <classname>IsisSession</classname> can give rise to one or multiple
+ <classname>IsisTransaction</classname>s. If running within a webapp or
+ the server-side of a client/server remoting, each
+ <classname>IsisSession</classname> will instantiate precisely one
+ <classname>IsisTransaction</classname>, automatically begun at the
+ beginning of the session and committed at the end. On the client-side
+ of a client/server deployment, an
+ <classname>IsisTransaction</classname> is created for each
+ client/server interaction.</para>
+
+ <para>The following look at the role of each of the components shown,
+ in each scope.</para>
+
+ <sect2>
+ <title>Application-level scope</title>
+
+ <para>The <classname>IsisSystem</classname> is the top-level object
+ that represents the running <emphasis>Isis</emphasis> instance.
+ Within this top-level object are a number of subsidiary
+ objects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <classname>DeploymentType</classname> is used to
+ categorise the "mode" in which <emphasis>Isis</emphasis> is
+ being used. This combines two different dimensions: whether
+ <emphasis>Isis</emphasis> is running in a server (multiuser) or
+ client context, and whether it is running in
+ exploration/prototyping/production. The
+ <classname>DeploymentType</classname> in effect can influence
+ which implementation of components are created (see <xref
+ linkend="sec.InstallerLookup" />).</para>
+ </listitem>
+
+ <listitem>
+ <para>the <classname>IsisConfiguration</classname> is the final
+ configuration after all components have been
+ loaded;eLoade</para>
+ </listitem>
+
+ <listitem>
+ <para>the <classname>IsisSessionFactory</classname> is used to
+ create <classname>IsisSession</classname>s as required (more on
+ this below)</para>
+ </listitem>
+
+ <listitem>
+ <para>the <classname>LogonFixture</classname> allows automatic
+ logon if running with a test/exploration mode
+ (<classname>DeploymentType</classname>)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Of the above top-level objects, the
+ <classname>IsisSessionFactory</classname> is by far the most
+ important, because it is responsible for creating
+ <classname>IsisSession</classname>s as and when required. There are
+ several elements to an <classname>IsisSession</classname>, and so
+ <classname>IsisSessionFactory</classname> delegates the
+ instantiation of these elements to its own subsidiary
+ objects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <classname>AuthenticationManager</classname> is used
+ for authenticated users into the system, and is used to
+ instantiate an <classname>AuthenticationSession</classname>.
+ This is discussed further in <xref
+ linkend="sec.SessionLevelScope" />.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <classname>PersistenceSessionFactory</classname> is
+ used to instantiate the corresponding
+ <classname>PersistenceSession</classname>. This is discussed
+ further in <xref linkend="sec.SessionLevelScope" />.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, the <classname>IsisSessionFactory</classname>
+ holds references to a number of other top-evel components, namely
+ <classname>AuthorizationManager</classname>, the
+ <classname>SpecificationLoader</classname> (ie the Isis metamodel),
+ the <classname>TemplateImageLoader</classname> (for loading
+ images/icons) and the <classname>UserProfileLoader</classname>
+ (responsible for interacting with the profile store
+ component).</para>
+ </sect2>
+
+ <sect2 id="sec.SessionLevelScope">
+ <title>Session-level scope</title>
+
+ <para>The <classname>AuthenticationSession</classname> holds the
+ credentials (basically: username and roles) of the user that is
+ currently (ie with respect to the current
+ <classname>IsisContext</classname>) interacting with
+ <emphasis>Isis</emphasis>. In principal this information could
+ change over time; for example a user might be added or removed from
+ roles.</para>
+
+ <para>The <classname>PersistenceSession</classname>, on the other
+ hand, is a somewhat more complex beast, consisting in turn
+ of:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>IsisTransactionManager</classname>, which is
+ responsible for managing <classname>IsisTransaction</classname>s
+ within the persistence session.</para>
+
+ <para>As mentioned above, when running as a webapp there is
+ precisely one <classname>IsisTransaction</classname> per
+ session, however when running as a client in client/server mode
+ there may be many transactions per session.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>ServicesInjector</classname>, which is
+ responsible for injecting domain services into each domain
+ object as it is instantiated.</para>
+
+ <para>Services are discussed further in <xref
+ linkend="sec.DomainServices" />.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>PojoAdapterFactory</classname>, which is an
+ implementation of the
+ <classname>oai.core.metamodel.adapter.ObjectAdapterFactory</classname>
+ <acronym>API</acronym>.</para>
+
+ <para>The default implementation instantiates
+ <classname>PojoAdapter</classname> as the corresponding
+ implementation of
+ <classname>oai.core.metamodel.adapter.ObjectAdapter</classname>.
+ There is further coverage of
+ <classname>ObjectAdapter</classname>s in <xref
+ linkend="sec.ObjectLifecycleManagement" />.</para>
+
+ <para>In principle this is an extension point; the
+ <emphasis>default runtime</emphasis> could be extended to
+ provide different implementations of
+ <classname>ObjectAdapterFactory</classname>. for example to
+ provide more extensive binding support for certain viewers, or
+ to provide a fine-grained notifications of changes to underlying
+ objects.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>ObjectFactory</classname>, which provides
+ different implementations for instantiating domain object
+ pojos.</para>
+
+ <para>This is the primary <acronym>API</acronym> that enables
+ lazy-loading and automatic tracking of dirty objects.
+ Specifically, the <classname>ObjectFactory</classname>
+ <acronym>API</acronym> is implemented to allow the bytecode
+ implementation to instantiate objects (they provide custom
+ subclasses which act as wrappers around the underlying
+ object).</para>
+
+ <para>In addition, the <classname>ClassSubstitutor</classname>
+ <acronym>API</acronym> should also be implemented; this allows
+ the metamodel to walk the graph ignoring the custom
+ subclasses.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>OidGenerator</classname>, which provides an
+ <acronym>API</acronym> to generate unique
+ <classname>Oid</classname>s (object identifiers) for each
+ persistent instance.</para>
+
+ <para>You can think of the <classname>OidGenerator</classname>
+ as a generalization of the automatic generation of primary keys
+ for entities (using a SQL Server <code>identity</code> keyword
+ or Oracle SEQUENCE). However, whereas a primary key id only
+ relates to persisted objects, <emphasis>Isis</emphasis>'
+ <emphasis>default runtime</emphasis> also allows
+ <classname>Oid</classname>s to be created for still-transient
+ objects. Because such objects may later be persisted, this
+ meanst that the value of the <classname>Oid</classname> can
+ change at this point. <emphasis>Isis</emphasis> automatically
+ manages this transition.</para>
+
+ <para><classname>OidGenerator</classname>s are also required to
+ return an <classname>OidStringifier</classname>, which is
+ capable of returning a string representation of the
+ <classname>Oid</classname>. This capability is exploited by some
+ viewers, such as the Restful viewer
+ <package>[oai.viewer:restful]</package>, where string
+ representations of <classname>Oid</classname>s are required.
+ Some <classname>Oid</classname> implementations can choose to
+ implement the <classname>DirectlyStringableOid</classname>
+ sub-interface, so can be serialized and deserialized into
+ strings very directly. Other implementations may rely on the
+ fact that all <classname>Oid</classname>s are also
+ <classname>oai.core.commons.encoding.Encodable</classname>. The
+ string representation for such Oids will however be rather long
+ and opaque.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>AdapterManager</classname>, which is
+ responsible for tracking the associations between domain object
+ pojos, <classname>ObjectAdapter</classname>s and
+ <classname>Oid</classname>s.</para>
+
+ <para>This, too, is discussed fruther in <xref
+ linkend="sec.ObjectLifecycleManagement" />.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The final scope is for transactions that are created within an
+ session.</para>
+ </sect2>
+
+ <sect2 id="sec.TransactionLevelScope">
+ <title>Transaction-level scope</title>
+
+ <para>The <classname>IsisTransactionManager</classname> (referenced
+ by <classname>PersistenceSession</classname>) is responsible for
+ creating an <classname>IsisTransaction</classname>. The
+ implementation used depends on the
+ <classname>PersistenceSession</classname>, but for the more common
+ case, object stores, the implementation that is used is
+ <classname>ObjectStoreTransaction</classname>. This in turn holds a
+ collection of <classname>PersistenceCommand</classname>s which
+ represent instructions to add, update or delete objects as required.
+ When the transaction is committed, each of these
+ <classname>PersistenceCommand</classname>s is executed by the
+ configured object store.</para>
+
+ <para>In addition to the commands, the IsisTransaction also holds
+ two further sub-components:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <classname>UpdateNotifier</classname> is used to
+ capture the list of objects that have been added, updated or
+ deleted (disposed of). This can be queried by other components
+ (such as viewers) as necessary (for example, to know which
+ objects to repaint).</para>
+
+ <para>Once changes are retrieved by client the notifier resets
+ its collection so that changes are only available once.</para>
+ </listitem>
+
+ <listitem>
+ <para>the <classname>MessageBroker</classname> is used to
+ capture any messages, warnings, or errors that either the system
+ or the domain objects themselves have raised.</para>
+
+ <para>Domain objects can raise messages using the
+ <classname>oai.applib.DomainObjectContainer</classname>,
+ automatically injected into all domain objects. The system may
+ raise messages if, for example, a concurrency exception
+ occurs.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In general it is invalid to access an object from any scope
+ once it has been closed. So, for example, the behaviour of the
+ <classname>AdapterManager</classname> of a
+ <classname>PersistenceSession</classname> is undefined once its
+ owning <classname>PersistenceSession</classname> is closed. The
+ exception to this rule is the <classname>UpdateNotifier</classname>
+ and <classname>MessageBroker</classname>. Other components in the
+ framework are free to access these even after the transaction has
+ completed, for example in order to repaint the view. See <xref
+ linkend="sec.IsisContext" /> for details on how to obtain these
+ components and any others.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec.IsisContext">
+ <title>Service Locator (<classname>IsisContext</classname>) and
+ <classname>DeploymentType</classname>s</title>
+
+ <para>The <emphasis>default runtime</emphasis> uses the service
+ locator pattern to make components (of different scopes) available.
+ This is implemented through the <classname>IsisContext</classname>
+ class.</para>
+
+ <para><classname>IsisContext</classname> itself is abstract; concrete
+ subclasses take responsibility for binding the services as
+ appropriate. For example, the default implementation for server-side
+ deployments is to use the
+ <classname>IsisContextThreadLocal</classname>, which (as might be
+ expected) binds the <classname>IsisContext</classname> singleton to
+ thread-local storage. This is, however, pluggable; the Wicket viewer
+ <package>[oai.viewer:wicket]</package> for example provides its own
+ implementation <classname>IsisContextForWicket</classname>, which
+ binds the IsisContext to an <ulink
+ url="http://wicket.apache.org">Apache Wicket</ulink>
+ <classname>org.apache.wicket.Session</classname>.</para>
+
+ <para>As noted above, in general it is invalid to access an object
+ from any scope once it has been closed; an
+ <classname>IllegalStateException</classname> will be thrown
+ otherwise.</para>
+
+ <para></para>
+
+ <para>*** TODO: discuss DeploymentType and ContextCategory</para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1 id="sec.ObjectLifecycleManagement">
+ <title>Object Lifecycle Management</title>
+
+ <para>Managing the lifecycle of domain objects is one of the major
+ responsibilities of the <emphasis>default runtime</emphasis>. Most of
+ the work goes on in the <classname>PersistenceSession</classname>
+ component, discussed earlier in <xref
+ linkend="sec.SessionLevelScope" />. In this section we dig a little
+ deeper into some of the internals of this component.</para>
+
+ <sect2>
+ <title><classname>ObjectAdapter</classname>s and
+ <classname>Oid</classname>s</title>
+
+ <para><emphasis>Apache Isis</emphasis> components do not deal
+ directly with domain object pojos; instead they are always wrapped
+ by an adapter, call <classname>ObjectAdapter</classname>. This has
+ two main responsibilities:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>it provides reference to the
+ <classname>ObjectSpecification</classname>, which describes the
+ structure (properties, collections, actions) of the object's
+ type</para>
+ </listitem>
+
+ <listitem>
+ <para>it provides reference to an <classname>Oid</classname>,
+ which is an opaque value that uniquely identifies the object
+ instance.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can think of <classname>ObjectAdapter</classname> as
+ equivalent to <classname>java.lang.Object</classname>, while
+ <classname>ObjectSpecification</classname> is in some sense
+ equivalent to <classname>java.lang.Class</classname>. The
+ <classname>Oid</classname> interface meanwhile is something akin to
+ a primary key identifier for an row in a relational database, but it
+ is slightly more abstract than that because it can also represent a
+ non-persisted object.</para>
+
+ <para>It is the <emphasis>metamodel</emphasis> module of
+ <emphasis>Isis</emphasis> <package>[oai.core:metamodel]</package>
+ defines these interfaces (<classname>ObjectAdapter,
+ ObjectSpecifation</classname> and <classname>Oid</classname>), the
+ object itself (<classname>ObjectAdapter</classname>), and the
+ object's identity (<classname>Oid</classname>). The metamodel itself
+ also provides an implementation of
+ <classname>ObjectSpecification</classname>.</para>
+
+ <para>The <emphasis>default runtime</emphasis> module
+ <package>[oai.runtimes:dflt]</package> provides an implementations
+ of the <classname>ObjectAdapter</classname> interface
+ (<classname>oai.runtimes.dflt.persistence.adapterfactory.pojo.PojoAdapter</classname>)
+ as well as an implementation of the <classname>Oid</classname>
+ interface. The actual implementation of <classname>Oid</classname>
+ will depend on the object store (persistence) mechanism that the
+ runtime has been configured to use.</para>
+ </sect2>
+
+ <sect2>
+ <title><classname>AdapterManager</classname></title>
+
+ <para>As already mentioned, the <classname>ObjectAdapter</classname>
+ maintains a reference to an <classname>Oid</classname> and the
+ underlying pojo domain object. To traverse in the other direction -
+ that is, from <classname>Oid</classname> to
+ <classname>ObjectAdapter</classname> or from pojo to
+ <classname>ObjectAdapter</classname> - the default runtime uses its
+ internal <classname>AdapterManager</classname> component, which
+ maintains two sets of maps. This is shown below:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/adapter-manager.png" scale="45" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The <classname>AdapterManager</classname> is an example of the
+ <ulink
+ url="http://martinfowler.com/eaaCatalog/identityMap.html">object-identity
+ map pattern</ulink> (as documented more fully in Martin Fowler's
+ Patterns of Enterprise Application Architecture). Whenever a domain
+ object pojo is handled by the system, and before an adapter for it
+ has been created, the runtime checks the
+ <classname>AdapterManager</classname> for the instance first, and
+ only creates an adapter if the pojo is not mapped. Similarly, if the
+ adapter has only an <classname>Oid</classname> value then the
+ <classname>AdapterManager</classname> is determine if the object's
+ adapter exists.</para>
+
+ <para>For value types (such as <classname>String</classname> or
+ <classname>java.math.BigDecimal</classname>), things are a little
+ different. All values <emphasis>do</emphasis> still have an
+ associated <classname>ObjectAdapter</classname>, however the
+ <classname>Oid</classname> of these is null, and these objects are
+ not stored within the <classname>AdapterManager</classname> maps. A
+ value is any object whose <classname>ObjectSpecification</classname>
+ has a <classname>ValueFacet</classname> associated with it.
+ Typically this is as a result of it have the
+ <classname>@Value</classname> annotation; or it might be one of the
+ built-in types supported by <emphasis>Isis</emphasis> (such as
+ <classname>String</classname>).</para>
+ </sect2>
+
+ <sect2>
+ <title>Aggregate roots and <classname>Oid</classname>
+ subtypes</title>
+
+ <para>Whereas value types have no <classname>Oid</classname>, all
+ other domain objects do:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Most domain objects that have an
+ <classname>Oid</classname> will be domain entities that,
+ moreover, are aggregate roots. That is, these are entities that
+ are intended to be directly referenced from other entities, and
+ have their own, independent identity.</para>
+
+ <para>For example, a <classname>Customer</classname>,
+ <classname>Product</classname> and <classname>Order</classname>
+ are all likely to be aggregate root entities.</para>
+ </listitem>
+
+ <listitem>
+ <para>Lists or sets also have an
+ <classname>Oid</classname>.</para>
+
+ <para>For example, the <classname>List<Order></classname>
+ held internally by a <classname>Customer</classname> to
+ represent its list of <classname>Order</classname>s will be
+ wrapped in an <classname>ObjectAdapter</classname> and have its
+ own <classname>Oid</classname>. Moreover, this
+ <classname>ObjectAdapter</classname> will be able to track
+ whether the list has been populated from the persistence
+ mechanism (so that the collection can be lazily loaded if
+ required).</para>
+
+ <para>However, such internal lists do not exist outside of their
+ owning entity, so these are considered "aggregated" by that
+ owning entity. The <classname>Oid</classname> of such objects is
+ an instance of type <classname>AggregatedOid</classname>, which
+ is basically the <classname>Oid</classname> of its owning entity
+ along with an Id for the collection of the object member in
+ question (eg "orders").</para>
+ </listitem>
+
+ <listitem>
+ <para>Entities can also be aggregated.</para>
+
+ <para>If an entity type is annotated with
+ <classname>@Aggregated</classname>, then it means that all
+ instances of that type are considered as non-root aggregated
+ entities, and will also be identified using an
+ <classname>AggregatedOid</classname>.</para>
+
+ <para>For example, <classname>OrderItem</classname> might be
+ considered an aggregate type (within its aggregate root,
+ <classname>Order</classname>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Marking an entity as aggregated may or may not impact how it
+ is persisted. For example, an XML or No-SQL (JSON-based) object
+ store might conceivably inline the persisted representation of the
+ aggregated entity within the document representing the aggregate
+ root. An RDBMS-based object store, on the other hand, might choose
+ to simply persist every entity in its own table (meaning that the
+ distinction between aggregate root entities vs aggregated entities
+ is less obvious).</para>
+
+ <para>For aggregate root entities, the actual
+ <classname>Oid</classname> implementation depends upon the
+ configured persistence mechanism. For example, if using the XML
+ object store then the <classname>SerialOid</classname>
+ implementation is used, with the
+ <classname>TimeBasedOidGenerator</classname> being used as the
+ <classname>OidGenerator</classname> (in other words, creating unique
+ instances based on the current time). On the other hand the SQL
+ object store happens to have its own <classname>SqlOid</classname>
+ implementation, which captures the value generated by the underlying
+ relational database.</para>
+ </sect2>
+
+ <sect2 id="sec.DomainServices">
+ <title>Domain Services</title>
+
+ <para>One of the responsibilities of the
+ <classname>IsisSystem</classname> is to obtain the list of domain
+ services that will be made available to the end-user and which are
+ automatically injected into the domain objects.</para>
+
+ <para>The default implementation is to load from the
+ <filename>isis.properties</filename> file, under the
+ <varname>isis.services.prefix</varname> and
+ <varname>isis.services</varname> keys:</para>
+
+ <programlisting>isis.services.prefix = org.apache.isis.example.claims.objstore.dflt
+isis.services = employee.EmployeeRepositoryDefault, claim.ClaimRepositoryDefault</programlisting>
+
+ <para>For each domain service class, a corresponding domain object
+ is instantiated, and then these are held as a simple list within
+ IsisSystem.</para>
+
+ <para>When a <classname>PersistenceSession</classname> is created,
+ all domain objects must be mapped with
+ <classname>ObjectAdapter</classname>s. Because domain services are
+ injected into domain objects, this applies to the domain objects too
+ (otherwise the domain objects would appear to hold an unknown
+ object).</para>
+
+ <para>Moreover, it is not valid for persisted domain objects to hold
+ references to non-persisted domain objects. We therefore "fool" the
+ rest of the framework by automatically creating and mapping
+ <classname>ObjectAdapter</classname>s for all the domain services
+ objects, with each set to being already persistent. The scope of
+ these <classname>ObjectAdapter</classname>s is the same as for any
+ other adapter within the <classname>PersistenceSession</classname>;
+ only as long as the <classname>PersistenceSession</classname> is
+ still open. When the subsequent
+ <classname>PersistenceSession</classname> is created,
+ <classname>ObjectAdapter</classname>s are created a-new for each
+ domain service.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Runtime Module</title>
+
+ <abstract>
+ <para>A run through of the main packages and classes that make up the
+ runtime module.</para>
+ </abstract>
+
+ <para>The runtime module <package>[oai.core:isis-core-runtime]</package>
+ is the "engine-room" of the default runtime, taking responsibility to
+ manage domain object (pojo) instances at runtime:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Each pojo is wrapped in an
+ <classname>ObjectAdapter</classname> (cf
+ <classname>java.lang.Object</classname>) from which the
+ <classname>ObjectSpecification</classname> (cf
+ <classname>java.lang.Class</classname>) can be obtained.</para>
+ </listitem>
+
+ <listitem>
+ <para>Associated with each <classname>ObjectAdapter</classname> is
+ an <classname>Oid</classname>: an opaque serializable identifier to
+ the object. The <emphasis>runtime</emphasis> module maintains a
+ 3-way identity map between these, allowing forward and reverse
+ lookups (<classname>AdapterManager</classname>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The runtime module also defines a number of APIs:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the most important such API is the
+ <classname>ObjectStore</classname> API. The
+ <emphasis>runtime</emphasis> module manages persistence and
+ transaction demarcation, with the actual storage of objects being
+ delegated to an object store implementation.</para>
+ </listitem>
+
+ <listitem>
+ <para>the other major API defined by the runtime module security
+ API, dealing with authentication and authorization.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition to all the above, the <emphasis>runtime</emphasis>
+ module defines a command-line bootstrapper, making it easy to bootstrap
+ Apache Isis from a main() or a JUnit test case.</para>
+
+ <sect1>
+ <title>Package Layering / Dependencies</title>
+
+ <para>The packages that reside within the <emphasis>runtime</emphasis>
+ have break into the following layers (top layer packages depending on
+ lower layers):</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/runtime/architectural-layers.png"
+ scale="70" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Alternatively, we can see the actual dependencies:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/runtime/package-dependencies.png"
+ scale="50" />
+ </imageobject>
+ </mediaobject>
+
+ <para>With one minor exception, there are no cycles between
+ packages.</para>
+ </sect1>
+
+ <sect1>
+ <title>Runtime, Runner, Installers</title>
+
+ <para></para>
+
+ <para></para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/runtime/architectural-layers-1.png"
+ scale="70" />
+ </imageobject>
+ </mediaobject>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>SystemUsingInstallers, and InstallerRegistry</title>
+
+ <para></para>
+
+ <para></para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/runtime/architectural-layers-2.png"
+ scale="80" />
+ </imageobject>
+ </mediaobject>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Web and Viewers</title>
+
+ <para></para>
+
+ <para></para>
+
+ <mediaobject>
+ <imageobject>
+
<TRUNCATED>