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:31 UTC
[34/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
----------------------------------------------------------------------
diff --git a/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml b/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
deleted file mode 100644
index a924ac6..0000000
--- a/core/src/docbkx/guide-runtime-to-incorporate/isis-default-runtime.xml
+++ /dev/null
@@ -1,2752 +0,0 @@
-<?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>
- <imagedata fileref="images/runtime/architectural-layers-3.png"
-
<TRUNCATED>