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:07 UTC
[10/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/isis-core.xml
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/core/src/docbkx/guide/isis-core.xml b/mothballed/docbkx/core/src/docbkx/guide/isis-core.xml
new file mode 100644
index 0000000..4fd748d
--- /dev/null
+++ b/mothballed/docbkx/core/src/docbkx/guide/isis-core.xml
@@ -0,0 +1,3156 @@
+<?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>
+
+ <author>
+ <firstname>Robert</firstname>
+
+ <surname>Matthews</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>
+
+ <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 variouys
+ 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>
+
+ <sect1>
+ <title>Who this Guide is For</title>
+
+ <para>This guide is written for programmers looking to understand how
+ the core framework of <emphasis>Apache Isis</emphasis> fits together,
+ including an understanding of its core <acronym>API</acronym>s. It is
+ divided into the following chapters:<itemizedlist>
+ <listitem>
+ <para>Architectural Overview</para>
+
+ <para>The introductory chapter discusses some of the main
+ architecture elements of the framework's design, distinguishing
+ and explaining the reason for the applib, the core modules, the
+ viewers, and the main <acronym>API</acronym>s exposed by the
+ core.</para>
+ </listitem>
+
+ <listitem>
+ <para>Chapters for each of core modules</para>
+
+ <para>This part of the guide goes through each of the modules that
+ make up the core framework. We also identify the main
+ <acronym>API</acronym>s exposed by the core: security, programming
+ models, and runtime.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>We <emphasis>don't</emphasis> however describe the implementations
+ of these <acronym>API</acronym>s; for these see their respective guides.
+ What that means is that we don't describe how to actually deploy an
+ <emphasis>Isis</emphasis> application here, because that depends upon
+ the runtime/viewer in use. See the relevant runtime documentation for
+ details.</para>
+
+ <para>You'll also find that <emphasis>this</emphasis> guide does explain
+ how to actually write the domain objects that make up an
+ <emphasis>Isis</emphasis> application; for that you should look to the
+ <emphasis>applib (application library)</emphasis> documentation.
+ Meanwhile, the <emphasis>programming model</emphasis> documentation
+ describe how to customize the default programming model to your own
+ ends. However this guide <emphasis>does</emphasis> explain why
+ <emphasis>Isis</emphasis> is architected to have an applib in the first
+ place, and it shows what the programming model looks like
+ <emphasis>inside</emphasis> of <emphasis>Isis</emphasis>.</para>
+ </sect1>
+
+ <sect1>
+ <title>Abbreviations used in this Guide</title>
+
+ <para><emphasis>Apache Isis</emphasis> is built using Maven, which
+ identifies every module with a <emphasis>groupId</emphasis>, an
+ <emphasis>artifactId</emphasis>, a <emphasis>version</emphasis>, and a
+ <emphasis>type</emphasis>. These are called the Maven
+ <emphasis>co-ordinates</emphasis>. In this guide we identify each module
+ using notation <package>(groupId:artifactId)</package>; you should
+ assume that the <emphasis>version</emphasis> is the latest version, and
+ the <emphasis>type</emphasis> is the default JAR artifact<footnote>
+ <para>Maven modules can create other artifacts too, such as a test
+ JAR artifact. This would be indicated with a type of test-jar. But
+ the default artifact is a regular JAR.</para>
+ </footnote>. Hence <package>(org.apache.isis:core)</package> is the
+ Maven module with a <emphasis>groupId</emphasis> of
+ <package>org.apache.isis</package> and an
+ <emphasis>artifactId</emphasis> of <package>core</package>.</para>
+
+ <para>As a further convenience, we use "oai" as an abbreviation for
+ <package>org.apache.isis</package>. Hence
+ <package>(oai.runtimes:dflt)</package> refers to the default runtime
+ module.</para>
+
+ <para>In this guide we also use the "oai" abbreviation within package
+ names. For example,
+ <package>oai.core.runtime.authentication.AuthenticationManager</package>
+ is an abbreviation of
+ <package>org.apache.isis.core.runtime.authentication.AuthenticationManager</package>.</para>
+ </sect1>
+ </preface>
+
+ <chapter id="chp.Intro">
+ <title>Architectural Overview</title>
+
+ <abstract>
+ <para>What's in this guide, it's relationship to the applib
+ documentation.</para>
+ </abstract>
+
+ <para><emphasis>Apache Isis</emphasis> is a full-stack open source
+ application development framework, designed to let you rapidly develop
+ enterprise business applications following a domain-driven philosophy.
+ Developing an application in <emphasis>Isis</emphasis> is - at least
+ initially - about focusing on the bit that matters to the business, the
+ core domain logic.</para>
+
+ <sect1>
+ <title>Hexagonal Architecture</title>
+
+ <para><emphasis>Apache Isis</emphasis>' architecture is a variant of the
+ typical <ulink
+ url="http://xunitpatterns.com/Layered%20Architecture.html">layered
+ architecture</ulink>, called the <ulink
+ url="http://alistair.cockburn.us/Hexagonal+architecture">hexagonal
+ architecture</ulink>. Like the layered architecture, the hexagonal
+ architecture distinguishes between the user interface layer, the
+ persistence (or infrastructure) layer, and the domain layer.
+ <emphasis>Apache Isis</emphasis>' version of this architectural style is
+ shown below.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/HexagonalArchitectureOverview.png"
+ scale="55" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The viewer modules constitute the presentation layer; these are
+ the means by which the end-user initiates an interaction with the domain
+ objects. The interaction is not directly with the domain objects,
+ though; instead think of the viewers as interacting through a "port"
+ into the hexagon. The <emphasis>Isis</emphasis> framework then adapts
+ this interaction for the domain objects. Indeed, another name for the
+ hexagonal architecture is the "ports and adapters" architecture.</para>
+
+ <para>As the domain objects are called, they are likely to interact with
+ other services. The most obvious of these is an interaction with the
+ persistence layer, either in terms of an update to themselves or the
+ creation/update or deletion of other objects. Again, though, this isn't
+ direct; instead the framework mediates/adapts to the configured
+ persistence mechanism.</para>
+
+ <para>Alternatively, though, the domain objects may interact with other
+ domain services. These services are specific to the application in
+ question, for example an email service, to publish an event, to generate
+ a <acronym>PDF</acronym>, to submit an order via a
+ <acronym>SOAP</acronym> web service etc. Here the framework is much less
+ involved; it merely will automatically inject any registered domain
+ services directly into domain objects in order that they can invoke the
+ service.</para>
+
+ <para>In order to support the interactions from the viewer to the domain
+ objects, and from the domain objects to the persistence mechanism, the
+ framework itself also calls out to other modules. The progmodel
+ <acronym>API</acronym> defines the programming conventions for the
+ domain objects; these conventions are used to build up a metamodel. Some
+ of these conventions depend on annotations, hence these dependency from
+ domain objects to the applib (application library) module which defines
+ such things. It's important to note that this is the only dependency
+ from domain objects to the framework, meaning that the domain objects
+ are basically pojos++. The other major <acronym>API</acronym> called by
+ the framework in order to do its job is the security
+ <acronym>API</acronym>, which is used for authentication and
+ authorization.</para>
+
+ <para>In the diagram you'll also see mention of the "default runtime".
+ In fact <emphasis>Apache Isis</emphasis> supports multiple runtimes. The
+ <emphasis>default runtime</emphasis> is reasonably heavyweight
+ implementation that supports defines a persistence
+ <acronym>API</acronym>, but also has support for remoting for
+ client/server deployments (whereby the server is configured for
+ persistence but the client's "persistence mechanism" is in fact the
+ proxy to the server). The default runtime also supports the concept of
+ profilestores, allowing user preferences to be stored and retrieved by
+ viewers. Finally, the default runtime defines a pluggable bytecode
+ enhancement <acronym>API</acronym>, allowing for transparent lazy
+ loading and object dirtying.</para>
+
+ <para>The default runtime is not the only runtime, however. One other
+ runtime supported is an "embedded runtime", allowing the embedding of
+ the Isis metamodel in any arbitrary application, for example a Maven
+ plugin. But we also expect to develop other - full-stack but more
+ lightweight - runtimes in the future. One such that is planned is to use
+ <ulink url="http://jcp.org/en/jsr/detail?id=299">CDI (JSR-299)</ulink>
+ for wiring, using <ulink url="http://db.apache.org/jdo/javadoc.html">JDO
+ 3.0</ulink> for the persistence <acronym>API</acronym>.</para>
+ </sect1>
+
+ <sect1>
+ <title>Core Framework</title>
+
+ <para>The core of <emphasis>Apache Isis</emphasis> is, well, the core
+ modules. These consist of a set of Maven modules grouped under a parent
+ module whose Maven co-ordinates are
+ <package>(org.apache.isis:core)</package>.</para>
+
+ <para>Each of the core modules has a Maven co-ordinate of
+ <package>[org.apache.isis.core:xxx</package>], where
+ <emphasis>xxx</emphasis> is one of:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>testsupport</para>
+
+ <para>The <emphasis>core testsupport</emphasis> module holds helper
+ classes to support writing unit tests in either JUnit or
+ JMock.</para>
+ </listitem>
+
+ <listitem>
+ <para>commons</para>
+
+ <para>The <emphasis>core commons</emphasis> module provides a set of
+ common utilities and language extensions for use across the rest of
+ the framework.</para>
+ </listitem>
+
+ <listitem>
+ <para>metamodel</para>
+
+ <para>The <emphasis>core metamodel</emphasis> module defines the
+ interfaces and classes which describe the structure of the domain
+ objects. The most obvious use of the metamodel is by the viewer
+ modules which use it in order to know how to render the user
+ interface. It is also used by some of the runtime/persistence
+ implementations.</para>
+ </listitem>
+
+ <listitem>
+ <para>progmodel</para>
+
+ <para>The <emphasis>core progmodel</emphasis> module provides a set
+ of reusable elements that are used to build up the metamodel. Some
+ of these depend upon annotations/interfaces in the
+ <emphasis>applib</emphasis> module, others merely define a
+ programming convention.</para>
+ </listitem>
+
+ <listitem>
+ <para>runtime</para>
+
+ <para>The <emphasis>core runtime</emphasis> module defines security
+ <acronym>API</acronym> (authentication and authorization) as well as
+ a number of other lesser <acronym>API</acronym>s and implementations
+ that are likely to be of use by most runtime implementations.</para>
+ </listitem>
+
+ <listitem>
+ <para>webapp</para>
+
+ <para>The <emphasis>core webapp</emphasis> module provides a number
+ of supporting filters, servlets and other classes for use by any
+ webapp-based viewer.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These modules are covered more extensively in the following
+ chapters.</para>
+ </sect1>
+
+ <sect1>
+ <title>Core <acronym>API</acronym>s</title>
+
+ <para>Across the core modules a number of key <acronym>API</acronym>s
+ are defined.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>programming model <acronym>API</acronym></para>
+
+ <para>The <emphasis>core metamodel</emphasis> module defines the
+ <classname>oai.core.metamodel.progmodel.ProgrammingModel</classname>
+ interface, which defines the rules and conventions that constitute
+ the programming model.</para>
+ </listitem>
+
+ <listitem>
+ <para>security <acronym>API</acronym></para>
+
+ <para>The <emphasis>core runtime</emphasis> module defines a
+ security <acronym>API</acronym> (specifically,
+ <package>oai.core.runtime.authentication.AuthenticationManager</package>
+ and
+ <package>oai.core.runtime.authorization.AuthorizationManager</package>)
+ as well as a number of other lesser <acronym>API</acronym>s and
+ implementations that are likely to be of use by most runtime
+ implementations.</para>
+ </listitem>
+
+ <listitem>
+ <para>runtime (persistence) <acronym>API</acronym></para>
+
+ <para>The responsibility of the runtime - broadly speaking - is to
+ perform object lifecycle management, persistence and (optionally)
+ client/server remoting. Runtimes may also offer other services, such
+ as user preference (or profile) management.</para>
+
+ <para>The runtime is not an <acronym>API</acronym> per-se, but
+ rather represents the environment in which the other functionality
+ provided by the <emphasis>Isis</emphasis> framework is called.
+ <emphasis>Isis</emphasis> has two runtime implementations:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <emphasis>default runtime</emphasis>
+ <package>(oai.core.runtimes:dflt)</package> that supports all of
+ the above (lifecycle, persistence, remoting and
+ profiles).</para>
+
+ <para>A key part of the design of the core runtime is the
+ <package>oai.core.runtime.system.context.IsisContext</package>
+ interface, which is used to obtain the current session<footnote>
+ <para>This interface is somewhat akin to <ulink
+ url="http://docs.jboss.org/hibernate/core/3.3/reference/en/html/tutorial.html">HibernateUtil</ulink>
+ class used in Hibernate.</para>
+ </footnote>.</para>
+ </listitem>
+
+ <listitem>
+ <para>the <emphasis>embedded runtime</emphasis>
+ <package>(org.apache.isis.core.runtimes:embedded)</package>, to
+ allow the <emphasis>Isis</emphasis> metamodel to be embedded
+ within otherwise bespoke applications, and in utilities such as
+ Maven plugins.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>At the time of writing no other runtimes are currently
+ implemented, but the intention is that other runtimes (eg using CDI,
+ JDO 3.0 etc) will be supported in the future.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Viewers</title>
+
+ <para>The viewers can be thought of as the outermost layer of
+ <emphasis>Isis</emphasis>, and calls upon the services of the core
+ framework and the configured runtime.</para>
+
+ <para>At the time of writing, all viewers have a dependency on the
+ <emphasis>default runtime</emphasis>, because this is the only runtime
+ available. In the future we expect that this will be decoupled so that
+ viewers can run against multiple different runtime
+ implementations.</para>
+
+ <para>Slightly confusingly, the <emphasis>default runtime</emphasis>
+ does also provide the facility to "launch" viewers, meaning that for
+ bootstrapping purposes at least the runtime calls the viewer rather than
+ the other way around. In order to support this, the viewer
+ implementation must provide an implementation of the runtime's
+ <package>oai.runtimes.dflt.runtime.viewer.IsisViewerInstaller</package>
+ interface. You'll see that the <acronym>DnD</acronym> viewer does do
+ this, but the Scimpi and Wicket viewers do not. However, once the viewer
+ is "up and running", the calls are strictly from the viewer to the
+ metamodel and runtime.</para>
+ </sect1>
+
+ <sect1>
+ <title>Maven Modules and Conventions</title>
+
+ <para><emphasis>Apache Isis</emphasis> is a large framework consisting
+ of multiple modules. In order to make it easier to navigate, you'll find
+ that we've aligned Maven module Ids with package names. For
+ example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <emphasis>core metamodel</emphasis> module is
+ <package>(oai.core:metamodel)</package>; all classes in this module
+ reside in the <package>oai.core.metamodel</package> package (or in
+ subpackages)</para>
+ </listitem>
+
+ <listitem>
+ <para>the <emphasis>applib</emphasis> module is
+ <package>(oai:applib)</package>; all classes in this module reside
+ in <package>oai.applib</package> package (or in subpackages).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We have also grouped modules of the same nature/interface to have
+ a common parent. For example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><package>(oai:viewers)</package> is the parent of
+ <package>(oai.viewers:dnd)</package> and
+ <package>(oai.viewers:html)</package> modules</para>
+ </listitem>
+
+ <listitem>
+ <para><package>(oai:security)</package> is the parent of
+ <package>(oai.security:dflt)</package> and
+ <package>(oai.security:ldap)</package> modules</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>There is also a top-level "parent" module,
+ <package>(oai:isis)</package>. This is used to define common
+ build/plugin dependencies, as well as a number of Maven profiles that
+ can be used to build subsets of the modules, and to build the Maven
+ website.</para>
+
+ <para>Finally, Isis also has an <package>(oai:release)</package> module.
+ The purpose of this module is simply to define a set of
+ <emphasis>Isis</emphasis> modules/versions that are compatible with each
+ other and thereby constitute a release. These can be imported
+ using:</para>
+
+ <programlisting><dependencies>
+ <dependency>
+ <groupId>org.apache.isis</groupId
+ <artifactId>release</artifactId>
+ <version>x.x.x</version>
+ <scope>import</scope>
+ </dependency>
+ ...
+</dependencies></programlisting>
+
+ <para>The <emphasis>Isis</emphasis> quickstart archetype makes use of
+ the release module in this way (as do the various examples that live in
+ <filename>.../trunk/examples</filename>).</para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title><emphasis>Test Support</emphasis> Module</title>
+
+ <abstract>
+ <para>Classes and interfaces in the
+ <package>oai.core.testsupport</package> module.</para>
+ </abstract>
+
+ <para>The <emphasis>testsupport</emphasis> module holds helper classes to
+ support writing unit tests using either JUnit or JMock. It should only
+ ever be added as a dependency with a scope of test:</para>
+
+ <para><programlisting><dependencies>
+ <dependency>
+ <groupId>org.apache.isis.core</groupId
+ <artifactId>testsupport</artifactId>
+ <version>x.x.x</version>
+ <emphasis><scope>test</scope></emphasis>
+ </dependency>
+ ...
+</dependencies></programlisting></para>
+
+ <sect1>
+ <title>JMock Support</title>
+
+ <para>The classes in the <package>oai.core.testsupport.jmock</package>
+ package provide convenience adapters for <ulink
+ url="http://jmock.org">JMock</ulink>. For example, they provide the
+ <classname>MockFixture</classname> interface that allows mocks
+ expectations to be managed as fixture objects in their own right
+ (thereby making such expectations reusable across tests). They also
+ provide subclasses of the <package>org.jmock.Mockery</package> class
+ with a number of convenience methods.</para>
+ </sect1>
+
+ <sect1>
+ <title>JUnit Support</title>
+
+ <para>The classes in the
+ <classname>oai.core.testsupport.junit</classname> package provide helper
+ classes designed, among other things, to make it easier to write value
+ types.</para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title><emphasis>Commons</emphasis> Module</title>
+
+ <abstract>
+ <para>Classes and interfaces in the <package>oai.core.commons</package>
+ module.</para>
+ </abstract>
+
+ <para>The <emphasis>core commons</emphasis> module provides a set of
+ common utilities for use across the rest of the framework. It also defines
+ a number of small, mostly internal, <acronym>API</acronym>s.</para>
+
+ <para>Generally it shouldn't be necessary to add an explicit dependency to
+ the <emphasis>commons</emphasis> module, because it will be depended upon
+ transitively by other modules in <package>oai.core</package>.</para>
+
+ <sect1>
+ <title>Package Layering / Dependencies</title>
+
+ <para>The packages that reside within <emphasis>commons</emphasis> have
+ break into the following layers (top layer packages depending on lower
+ layers):</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/common/architecture-perspective.png"
+ scale="80" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Alternatively we can see the actual dependencies:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/common/composition-perspective.png"
+ scale="80" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The relatively small number of dependencies between these packages
+ shows the extent to which the utility classes in common are independent
+ of each other.</para>
+ </sect1>
+
+ <sect1>
+ <title>APIs</title>
+
+ <sect2 id="sec.ComponentAndInstallerApi">
+ <title><classname>Component</classname> and
+ <classname>Installer</classname> <acronym>API</acronym></title>
+
+ <para><emphasis>Isis</emphasis> is a modular framework, and the
+ <classname>Component</classname> interface (in
+ <package>oai.core.commons.components</package> package) represents
+ this abstraction. For example, an authentication manager is a
+ <classname>Component</classname>, and so too is an adapter map (for
+ tracking object identities).</para>
+
+ <para><classname>Component</classname> has three subinterfaces to
+ represent different scopes (or lifetimes) of component instances,
+ namely:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>ApplicationScopedComponent</classname>, for
+ components that exist for the duration of the application</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>SessionScopedComponent</classname> , for
+ components that are created a-new for each session, and</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>TransactionScopedComponent</classname>, for
+ components that are bound to a single transaction.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For webapp/server-based deployments, a session is created for
+ each interaction<footnote>
+ <para>Just like JPA or Hibernate sessions.</para>
+ </footnote>. There is typically just one transaction per
+ session.</para>
+
+ <para>For client/standalone deployments, the session lasts for the
+ duration of the application, and so is one-to-one with the application
+ scope. For these cases a transaction is used to wrap each
+ client/server interaction<footnote>
+ <para>Strictly speaking, this is a statement about how the the
+ <emphasis>default runtime</emphasis> implementation works. Other
+ runtimes could conceivably take a different approach. If you are
+ only intending to use webapp-based viewers, then don't worry about
+ it... <emphasis>Isis</emphasis> works similarly to
+ JPA/Hibernate.</para>
+ </footnote>.</para>
+
+ <para>Closely related to <classname>Component</classname> is the
+ <classname>Installer</classname> interface, which acts as a
+ <classname>Component</classname> factory. Each Installer provides a
+ type (a string) and a name (also a string), and the combination of
+ (type, name) is expected to be unique. For example, the DnD viewer has
+ a type of "viewer" and a name of "dnd".</para>
+
+ <para>This (type, name) combination is used to determine the
+ configuration files that are searched for when the
+ <classname>Component</classname> is created. Each
+ <classname>Component</classname>'s <classname>Installer</classname>
+ will search for at least two property files:
+ <filename>type.properties</filename> and
+ <filename>type_name.properties</filename>. For example, the DnD viewer
+ will search for both <filename>viewer.properties</filename> and also
+ <filename>viewer_dnd.properties</filename> file<footnote>
+ <para>In fact, it is possible for an
+ <classname>Installer</classname> to nominate additional property
+ files; this is sometimes appropriate where a
+ <classname>Component</classname> does double-duty and plays more
+ than one role. At the time of writing this capability was only
+ used by the components that install client/server remoting for the
+ <emphasis>default runtime</emphasis> module.</para>
+ </footnote>. An Installer can also indicate whether a missing config
+ file should be treated as an error or can be ignored (generally the
+ latter).</para>
+ </sect2>
+
+ <sect2 id="sec.ConfigurationApi">
+ <title><classname>IsisConfiguration</classname> and
+ <classname>IsisConfigurationBuilder</classname>
+ <acronym>API</acronym></title>
+
+ <para>The <classname>IsisConfigurationBuilder</classname> (in
+ <package>oai.core.commons.config</package> package) is used to hold
+ the "current" configuration; as (the <classname>Installer</classname>
+ for) <classname>Component</classname>s are loaded each indicates the
+ property file(s) to load, and these are used to update the current
+ configuration held within
+ <classname>IsisConfigurationBuilder</classname>. The "current"
+ configuration is initially just the properties in the
+ <filename>isis.properties</filename> file (see <xref
+ linkend="sec.ResourceStreamApi" /> for details on where this file is
+ actually loaded from) .</para>
+
+ <para>When the <classname>Component</classname> is actually
+ instantiated, it is handed an immutable
+ <classname>IsisConfiguration</classname> that can be thought of as a
+ snapshot of the set of properties held by the
+ <classname>IsisConfigurationBuilder</classname>. A consequence of this
+ design is that different <classname>Component</classname>s will have
+ references to different <classname>IsisConfiguration</classname>
+ objects; though all should always have access to "their"
+ properties.</para>
+
+ <para>Using properties specified in the configuration files is done by
+ get the <classname>IsisConfiguration</classname> singleton from the
+ context and using one of the lookup methods to get a value, as the
+ example below shows. The <literal
+ moreinfo="none">Configuration.ROOT</literal> constant provides the
+ base property name ("isis."). If no value is found with the specified
+ property name exists then null (or 0 or false) will be
+ returned.</para>
+
+ <programlisting format="linespecific">String formatRequired = getConfiguration().getString(Configuration.ROOT + "value.format.date");</programlisting>
+ </sect2>
+
+ <sect2>
+ <title
+ id="sec.ResourceStreamApi"><classname>ResourceStreamSource</classname>
+ <acronym>API</acronym></title>
+
+ <para>The <classname>ResourceStreamSource</classname> interface (in
+ <package>oai.core.commons.resource</package> package) is an
+ abstraction over locating resource files. It is used predominantly to
+ locate configuration files (see <xref
+ linkend="sec.ConfigurationApi" />), with implementations to load from
+ the config directory or from the classpath.</para>
+
+ <para>Different implementations of
+ <classname>IsisConfigurationBuilder</classname> use
+ <classname>ResourceStreamSource</classname> in order to search for
+ config files in specific locations. In principle it would be
+ straightforward to write a new implementation of
+ <classname>ResourceStreamSource</classname> that loads config files
+ from some other location (eg LDAP, the Windows registry or a database)
+ and then write a new <classname>IsisConfigurationBuilder</classname>
+ to use it.</para>
+ </sect2>
+
+ <sect2>
+ <title>Encoding <acronym>API</acronym></title>
+
+ <para>The <package>oai.core.commons.encoding</package> package
+ provides a number of classes to support the custom serialization of
+ elements of any element:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/common/encoding-classdiagram.png"
+ scale="35" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The <classname>DataInputExtended</classname> and
+ <classname>DataOutputExtended</classname> interfaces are
+ straightforward extensions of <classname>java.io.DataInput</classname>
+ and <classname>java.io.DataOutput</classname> respectively, simply
+ adding the capability to serialize arrays of primitives. The
+ <classname>DataInputStreamExtended</classname> and
+ <classname>DataOutputStreamExtended</classname> implement these
+ interfaces, providing the ability to read from/write to an underlying
+ <classname>java.io.InputStream</classname>.</para>
+
+ <para>Finally, the <classname>Encodable</classname> interface defines
+ a contract for objects to write themselves to a
+ <classname>DataOutputStreamExtended</classname>, with an implied
+ contract that they can be re-constructed from a corresponding
+ <classname>DataInputStreamExtended</classname>.</para>
+
+ <para>The primary usage of the encoding API is to enable client/server
+ remoting, as supported by the <emphasis>default runtime</emphasis>
+ implementation. However, it is also used in order to create
+ <classname>Memento</classname>s of domain objects (again, a capability
+ of the <emphasis>default runtime</emphasis>). This is used by some
+ viewers in order to maintain a handle on transient (not-yet-persisted)
+ objects.</para>
+ </sect2>
+
+ <sect2 id="sec.AuthenticationSession">
+ <title><classname>AuthenticationSession</classname> Definition</title>
+
+ <para>The <classname>AuthenticationSession</classname> interface (in
+ the <package>oai.core.commons.authentication</package> package)
+ provides a representation of an authenticated user within the
+ system.</para>
+
+ <para>Also worth mentioning is the utility class
+ <classname>AuthenticationSessionUtils</classname> can be used to
+ create an <classname>oai.applib.security.UserMemento</classname>,
+ which is the corresponding type within the applib (that is, the
+ identity of the authenticated user as the domain objects understand
+ it).</para>
+
+ <para>The interface to actually authenticate users and create
+ <classname>AuthenticationSession</classname>s - namely
+ <classname>AuthenticationManager</classname> - is defined in the
+ <emphasis>core runtime</emphasis> module (see <xref
+ linkend="chp.Runtime" />). This shouldn't be confused with
+ <classname>AuthenticationSessionProvider</classname> which merely
+ returns the current <classname>AuthenticationSession</classname>
+ <emphasis>if one exists</emphasis>.</para>
+ </sect2>
+
+ <sect2>
+ <title><classname>Debuggable</classname>
+ <acronym>API</acronym></title>
+
+ <para>The <classname>Debuggable</classname> interface(in the
+ <classname>oai.core.commons.debug</classname> package) is used by some
+ <classname>Component</classname>s in order to build structured string
+ representations of themselves for debug purposes. A good example is
+ the debug menu options available within the DnD viewer.</para>
+ </sect2>
+
+ <sect2>
+ <title>Hamcrest <classname>Matcher</classname>s</title>
+
+ <para>The <classname>IsisMatchers</classname> class (in the
+ <classname>oai.core.commons.matchers</classname> package) provides a
+ collection of <ulink url="http://hamcrest.org">Hamcrest
+ </ulink><classname>Matcher</classname>s for use in both tests and also
+ production code.</para>
+ </sect2>
+
+ <sect2>
+ <title><classname>Ensure</classname> API</title>
+
+ <para>The <classname>Ensure</classname> class (in the
+ <package>oai.core.commons.ensure</package> package) allows assertions
+ to be made about arguments, state or general context, and uses
+ Hamcrest <classname>Matcher</classname>s to express those
+ assertions.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.MetaModel">
+ <title><emphasis>Metamodel</emphasis> Module
+ (<classname>ObjectSpecification</classname>s)</title>
+
+ <abstract>
+ <para>First of two chapters concerning the classes and interfaces in the
+ <package>oai.core.metamodel</package> module, focusing on the
+ <classname>ObjectSpecification</classname> and related
+ interfaces.</para>
+ </abstract>
+
+ <para>The core <emphasis>metamodel</emphasis> module defines the
+ interfaces and classes that make up the <emphasis>Apache Isis</emphasis>
+ metamodel. This metamodel is at the very heart of
+ <emphasis>Isis</emphasis>, and used in numerous ways:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>by viewers to obtain information about the domain objects, so
+ that they can be rendered in a generic object-oriented user
+ interface;</para>
+ </listitem>
+
+ <listitem>
+ <para>by persistence mechanisms (within the <emphasis>default
+ runtime</emphasis> module, <package>(oai.runtimes:dflt)</package>) to
+ determine which data is to be persisted;</para>
+ </listitem>
+
+ <listitem>
+ <para>by client/server remoting (within the <emphasis>default
+ runtime</emphasis> module) , to marshall domain objects automatically
+ between different tiers;</para>
+ </listitem>
+
+ <listitem>
+ <para>to provide the ability to provide XML Snapshots (through the
+ <classname>XmlSnapshot</classname> utility class, in the
+ <emphasis>core runtime</emphasis> module,
+ <package>(oai.core:runtime)</package>).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition, the metamodel provides a mechanism for the framework
+ and the clients of the framework to access and manipulate the domain
+ objects by wrapping them in an adapter. This is an important point: the
+ framework and its clients never interact with the domain objects
+ directly.</para>
+
+ <para>Note however that the <emphasis>metamodel</emphasis> module does not
+ itself define the programming model conventions; that is the
+ responsibility of the configured programming model (the default being the
+ one defined in the <emphasis>default progmodel</emphasis>
+ <package>(oai.progmodels:dflt)</package>.</para>
+
+ <sect1>
+ <title>Package Layering / Dependencies</title>
+
+ <para>The packages that reside within <emphasis>core
+ metamodel</emphasis> break into the following layers (top layer packages
+ depending on lower layers):</para>
+
+ <screenshot>
+ <screeninfo>Top-level Architecture Diagram with SpecLoader
+ expanded</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/metamodel/architecture-diagram-top-level-with-specloader-expanded.png"
+ scale="110" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Note that the diagram shows the <package>specloader</package>
+ package and also its subpackages. It also indicates that there is a
+ tangle (bidirectional dependencies)<footnote>
+ <para>Not a good thing, we recognize. But refactor to eliminate this
+ would considerably complicate the codebase.</para>
+ </footnote>Alternatively we can see the actual dependencies between
+ packages (again, with that tangle highlighted):</para>
+
+ <screenshot>
+ <screeninfo>Composition Diagram</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/metamodel/composition-diagram-top-level.png"
+ scale="70" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </sect1>
+
+ <sect1 id="sec.ObjectSpecifications">
+ <title><classname>ObjectSpecification</classname>s and the
+ <classname>SpecificationLoader</classname></title>
+
+ <para>To make the domain objects useful within the framework the
+ objects' public interfaces must be exposed. <emphasis>Isis</emphasis>
+ uses a number of techniques to do this, but the predominant one is the
+ Java reflection <acronym>API</acronym>s (in the
+ <package>java.lang.reflect</package> package), a process we call
+ introspection. These are used to determine what properties and
+ collections an object has, what behaviour it can offer, and to find
+ other information such as the object's title, a suggested order of its
+ fields, and when its actions can or can't be used. It also is used to
+ flag the type of object (abstract, lookup, object, value, and whether
+ persistable); to refer to its superclass, any inteferfaces it implements
+ and to list any subclasses.</para>
+
+ <para>The details about this interface are recorded in an instance of
+ <classname>ObjectSpecification</classname> (in the
+ <package>oai.core.metamodel.spec</package> package). As each class of
+ domain object is loaded into the system its corresponding instance of
+ <classname>ObjectSpecification</classname> is generated. You can think
+ of <classname>ObjectSpecification</classname> as analogous to
+ <classname>java.lang.Class</classname>.</para>
+
+ <sect2>
+ <title><classname>SpecificationLoader</classname> component</title>
+
+ <para>The specification object can be retrieved directly, by name or
+ class, from the <classname>SpecificationLoader</classname>
+ component<footnote>
+ <para>For historical reasons the
+ <classname>SpecificationLoader</classname> component is also
+ sometimes called the reflector; indeed
+ <classname>ObjectReflector</classname> is a subinterface that is
+ used internally.</para>
+ </footnote></para>
+
+ <para>. When a domain object is used within the framework the
+ <classname>SpecificationLoader</classname> instance is asked for the
+ <classname>ObjectSpecification</classname> of the domain object's
+ class. The first time that a class is requested the loader is
+ responsible for performing the introspection and creating a complete
+ <classname>ObjectSpecification</classname>. Thereafter the
+ specification is returned from a cache.</para>
+
+ <para>The set of <classname>ObjectSpecification</classname>s built up
+ by the <classname>SpecificationLoader</classname> are all those that
+ are reachable from the service classes (defined in
+ <filename>isis.properties</filename> configuration file under
+ <emphasis>isis.services</emphasis> key). Because cycles between
+ <classname>ObjectSpecification</classname>s are permitted (that is,
+ <classname>ClassA</classname> can reference
+ <classname>ClassB</classname> and <classname>ClassB</classname> can
+ reference <classname>ClassA</classname>), the creation of
+ <classname>ObjectSpecification</classname>s is actually a two-stage
+ process. When a class' <classname>ObjectSpecification</classname> is
+ being created, any prerequisite specifications (for its class members)
+ will be created if necessary, however those prerequisites will not
+ flagged as not yet "introspected". Only when those prerequisite
+ <classname>ObjectSpecification</classname>s are actually requested by
+ name will their introspection be formed. This prevents infinite loops
+ from occurring in the
+ <classname>SpecificationLoader</classname>.</para>
+
+ <para>It is also possible - and common - to obtain the
+ <classname>ObjectSpecification</classname> from the domain object's
+ adapter (the <classname>ObjectAdapter</classname> interface, discussed
+ in <xref linkend="sec.ObjectAdapter" />).</para>
+
+ <sect3>
+ <title>Accessing the
+ <classname>SpecificationLoader</classname></title>
+
+ <para>If using the <emphasis>default runtime</emphasis> module
+ <package>(oai.runtimes:dflt)</package>, then the
+ <classname>SpecificationLoader</classname> can be accessed using
+ <methodname>IsisContext.getSpecificationLoader()</methodname>. It is
+ an application-scoped component, meaning that a single instance is
+ used for the duration of the application running.</para>
+
+ <para>Other runtime implementations will (are likely to) use
+ dependency injection to make the
+ <classname>SpecificationLoader</classname> available.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="sec.ObjectMembers">
+ <title><classname>ObjectMember</classname>s</title>
+
+ <para>One of the main purposes of
+ <classname>ObjectSpecification</classname> is to describe the
+ structure of the domain object to which it relates, in other words the
+ members of that object's class. These are represented by
+ (sub-)interfaces of the <classname>ObjectMember</classname> interface
+ (in the <package>oai.core.metamodel.spec.feature</package> package).
+ The main sub-interfaces of <classname>ObjectMember</classname> are
+ <classname>OneToOneAssociation</classname>,
+ <classname>OneToManyAssociation</classname> and
+ <classname>ObjectAction</classname>.</para>
+
+ <para>The <methodname>ObjectSpecification#getProperties()</methodname>
+ method returns a list of <classname>OneToOneAssociation</classname>s
+ that represent the properties (eg
+ <methodname>Order#getShipDate()</methodname> or
+ <methodname>Order#getCustomer()</methodname>), while
+ <methodname>ObjectSpecification#getCollections()</methodname> returns
+ <classname>OneToManyAssociation</classname>s to represent collections
+ (eg <methodname>Order#getLineItems()</methodname>). Properties and
+ collections are typically rendered in some sort of form within a
+ viewer. Any remaining public methods (eg
+ <methodname>Order#cancel()</methodname>) are represented as actions,
+ accessible using
+ <methodname>ObjectSpecification#getActions()</methodname> and
+ returning a list of <classname>ObjectAction</classname>s. These are
+ typically rendered as menu items or links in viewers.</para>
+
+ <para>The <classname>OneToOneAssociation</classname>,
+ <classname>OneToManyAssociation</classname> and
+ <classname>ObjectAction</classname> interfaces all provide the ability
+ to interact with the underlying domain object, allowing viewers to
+ determine whether the property/collection/action is visible, is
+ enabled/disabled, and whether a new value/argument is valid.</para>
+
+ <para>It is also possible to obtain individual class members. For
+ example, an individual property can be accessed via the
+ <methodname>getProperty(String)</methodname> method, where the sole
+ parameter is the the identifier of the property. In the case of a
+ property, its identifier will be the name of the property method with
+ the <emphasis>get</emphasis> prefix removed, and the first character
+ of the remaining string converted to lowercase, so
+ <methodname>getCustomerId()</methodname> become
+ <emphasis>customerId</emphasis>. A similar pattern is used for
+ collections, while actions have an identifier that also takes into
+ account the parameters. In fact, the rules for constructing
+ identifiers are available within the applib, in the
+ <classname>oai.applib.Identifier</classname> class.</para>
+
+ <para>The complete list of properties/collections/actions is used for
+ things like persistence and remoting, however user interfaces need to
+ consider what properties they show to avoid making hidden or
+ unauthorised properties visible. To selectively get hold of all
+ associations (properties and collections) the
+ <methodname>getAssociations(Filter<ObjectAssociation>)</methodname>
+ method should be used<footnote>
+ <para>Rather than reinvent a filter API, the core framework reuses
+ the applib's
+ <classname>oai.applib.filter.Filter<T></classname>
+ class</para>
+ </footnote>, allowing us to set up a search filter based on any
+ criteria that might be relevant. Typically views are created using
+ only dynamically visible properties (so hidden fields are not visible
+ and do not have any screen space reserved form them). However, in the
+ case of a table the view will require a column for each
+ <emphasis>potentially</emphasis> available (statically visible)
+ property has a column created for it, but only show a value in the
+ cell if the property is visible for the object in question
+ (dynamically visible). To support this, two useful predefined
+ instances are the available:
+ <methodname>ObjectAssociationFilters.STATICALLY_VISIBLE_ASSOCIATIONS</methodname>
+ and the
+ <methodname>ObjectAssociationFilters.dynamicallyVisible(ObjectAdapter)</methodname>
+ factory method.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec.HowTheMetaModelIsBuiltUpInternally">
+ <title>How the metamodel is built up internally</title>
+
+ <para>As already explained, the
+ <classname>SpecificationLoader</classname> is responsible for building
+ up completed <classname>ObjectSpecification</classname>s, one for each
+ class that is reachable within the domain model. Moreover to avoid
+ cyclic dependencies, these <classname>ObjectSpecification</classname>s
+ are built-up in two stages; initially they are created but not fully
+ built (introspected); only when required does introspection take
+ place.</para>
+
+ <para>This section goes into some of the internals as to how
+ introspection process works.</para>
+
+ <sect2 id="sec.FacetFactory">
+ <title><classname>FacetFactory</classname>s and
+ <classname>Facet</classname>s</title>
+
+ <para>The first thing that <emphasis>Isis</emphasis> does is to create
+ a <classname>FacetedMethodsBuilder</classname> for each
+ <classname>ObjectSpecification</classname>. This is a helper object
+ that co-ordinates the identification of the object members (ie the
+ properties, collections and actions) of the
+ <classname>ObjectSpecification</classname>. Each such object member is
+ represented as a <classname>FacetedMethod</classname>. You can think
+ of this as analogous to
+ <methodname>java.lang.reflect.Method</methodname>, and it does indeed
+ wrap an instance of such a <classname>Method</classname>. We'll get
+ onto the "faceted" part of that name in just a minute.</para>
+
+ <para>The actual hard work of building up the metamodel, though, is
+ done by a collection of <classname>FacetFactory</classname>s. Each
+ <classname>FacetFactory</classname> is responsible for understanding a
+ specific element of the programming model. For example, one
+ <classname>FacetFactory</classname> looks for the
+ <methodname>disableXxx()</methodname> method that is used to disable
+ (grey out) an object member, another looks for
+ <classname>@Hidden</classname> that will hide an object member,
+ another looks for <classname>@RegEx</classname> that can be used to
+ validate property proposed values or action parameter arguments. Each
+ of these pieces of knowledge is represented as a
+ <classname>Facet</classname>, and is attached to the corresponding
+ <classname>FacetedMethod</classname> (hence its name).</para>
+
+ <para>Each of the methods in <classname>FacetFactory</classname>
+ retrieves a "context" object, which provides a mechanism to remove
+ methods so that subsequent <classname>FacetFactory</classname>s do not
+ consider them. For example, if a supporting
+ <methodname>disableXxx()</methodname> method is noticed while
+ processing a <methodname>getXxx()</methodname> property or collection,
+ then the <classname>FacetFactory</classname> in question will remove
+ this method. This design means that the
+ <classname>FacetFactory</classname> that identifies actions - which
+ are taken to be all "remaining" public actions - will not
+ inadvertantly create an action for these supporting methods.</para>
+
+ <para>If you explore the type hierarchy then you'll see that
+ <classname>FacetMethod</classname> implements
+ <classname>FacetHolder</classname>, and it is this interface through
+ which the <classname>FacetFactory</classname>s work. You might also
+ note that <classname>ObjectSpecification</classname> also implements
+ <classname>FacetHolder</classname>, as does
+ <classname>FacetedMethodParameter</classname>, which represents an
+ action parameter. What that means is that
+ <classname>FacetFactory</classname>s can also add
+ <classname>Facet</classname>s to these other types too. The interface
+ for <classname>FacetFactory</classname> reflects this, having methods
+ to handle the processing of a class, a method and an action parameter.
+ All of these can have Facets.</para>
+
+ <para>To summarize: the Isis metamodel has a type that is equivalent
+ to a <classname>java.lang.Class</classname>
+ (<classname>ObjectSpecification</classname>), to a
+ <classname>java.lang.reflect.Method</classname>
+ (<classname>FacetedMethod</classname>) and to an action parameter
+ (<classname>FacetedMethodParameter</classname>). Each of these can
+ have a set of <classname>Facet</classname>s attached to it, and these
+ <classname>Facet</classname>s <emphasis>are</emphasis> the metadata
+ for each such element.</para>
+ </sect2>
+
+ <sect2>
+ <title>Identifying object members</title>
+
+ <para>Recall that the <classname>FacetedMethodsBuilder</classname> is
+ responsible for co-ordinating the building of the
+ <classname>FacetMethod</classname>s of its owning
+ <classname>ObjectSpecification</classname>. The first step involves
+ identifying the actual properties, collections and actions of that
+ <classname>ObjectSpecification</classname> (based on the underlying
+ <classname>java.lang.Class</classname>). To do this, the
+ <classname>FacetedMethodsBuilder</classname> searches the set of
+ <classname>FacetFactory</classname>s for a factory that implements the
+ <classname>PropertyOrCollectionIdentifyingFacetFactory</classname>.
+ From these two collections of <classname>FacetedMethod</classname>s
+ are created, one set to represent the properties and the other to
+ represent the collections.</para>
+
+ <para>Once all properties and collections have been identified, all
+ remaining <code>public</code> methods are assumed to be actions. These
+ form a third set of <classname>FacetedMethod</classname>s.</para>
+ </sect2>
+
+ <sect2 id="sec.MemberLayoutArranger">
+ <title>Ordering Members
+ (<classname>MemberLayoutArranger</classname>)</title>
+
+ <para>The <classname>FacetedMethodsBuilder</classname>'s job is done
+ once all the <classname>FacetedMethod</classname>s have been
+ identified. At this point, the
+ <classname>ObjectSpecification</classname> takes over and completes
+ the job of building itself. The first task is to re-order the
+ identified members (still in the form of
+ <classname>FacetMethod</classname>s). It does this by delegating to a
+ <classname>MemberLayoutArranger</classname> which is used returns the
+ members in the required order.</para>
+
+ <para><note>
+ <para>The current implementation of MemberLayoutArranger orders
+ the members as per the <classname>@MemberOrder</classname>
+ annotation. In the future this component may take responsibility
+ for more sophisticated layout arranger, to handle column-based
+ layouts. This will require a change to its
+ <acronym>API</acronym>.</para>
+ </note></para>
+ </sect2>
+
+ <sect2>
+ <title>Creating <classname>ObjectMember</classname>s (wrapping
+ <classname>FacetedMethod</classname>s)</title>
+
+ <para>After the <classname>FacetedMethod</classname>s have been
+ ordered, they are then wrapped in the appropriate subclass of
+ <classname>ObjectMember</classname> (already discussed, see <xref
+ linkend="sec.ObjectMembers" />), in other words as a
+ <classname>OneToOneAssociation</classname>,
+ <classname>OneToManyAssociation</classname> or as an
+ <classname>ObjectAction</classname>. These objects provide a number of
+ methods that allow the clients of the metamodel (eg specifically,
+ viewers) to interact with underlying domain objects (see <xref
+ linkend="sec.ObjectAdapter" />) through the metamodel.</para>
+ </sect2>
+
+ <sect2 id="sec.FacetDecorator">
+ <title>Decorating <classname>Facet</classname>s
+ (<classname>FacetDecorator</classname>)</title>
+
+ <para>The last major step of building the metamodel is to decorate any
+ <classname>Facet</classname>s, using any registered
+ <classname>FacetDecorator</classname>s. Decorated
+ <classname>Facet</classname>s allow additional behaviour to be added
+ to already identified <classname>Facet</classname>s, and so are useful
+ for adding internationalization and (in the client/server remoting
+ support provided by the <emphasis>default runtime</emphasis>),
+ transactional control.</para>
+
+ <para><classname>FacetDecorator</classname>s are specified as a
+ comma-separated list in the <emphasis>isis.properties</emphasis>
+ configuration file using the
+ <code>isis.reflector.facet-decorators</code> key. For example:</para>
+
+ <programlisting format="linespecific">isis.reflector.facet-decorators=resource-i18n</programlisting>
+
+ <para>will install a <classname>FacetDecorator</classname> for
+ internationalization that loads from a
+ <classname>java.util.ResourceBundle</classname>.</para>
+
+ <para>The core <classname>FacetDecorator</classname> implementations
+ are in the <emphasis>core progmodel</emphasis> module (see <xref
+ linkend="chp.ProgModel" />).</para>
+
+ <para><note>
+ <para>The <classname>FacetDecorator</classname> design actually
+ predates use of <classname>Facet</classname>s within the Isis
+ metamodel (we renamed it to <classname>FacetDecorator</classname>
+ after the fact). If you dig into the <classname>Facet</classname>
+ <acronym>API</acronym> you'll see that it supports the concept of
+ an underlying <classname>Facet</classname>
+ (<methodname>Facet#getUnderlyingFacet()</methodname>). At some
+ stage we hope to remove <classname>FacetDecorator</classname>s
+ completely and simply use the underlying
+ <classname>Facet</classname> approach; see <ulink
+ url="https://issues.apache.org/jira/browse/ISIS-69">ISIS-69</ulink>
+ in JIRA.</para>
+ </note></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="sec.MetaModelValidator">
+ <title>MetaModel Validation
+ (<classname>MetaModelValidator</classname>)</title>
+
+ <para>After all <classname>ObjectSpecification</classname>s have been
+ identified and loaded, the <classname>SpecificationLoader</classname>
+ calls out to the configured <classname>MetaModelValidator</classname>
+ (defined in the
+ <package>org.apache.isis.core.metamodel.specloader.validator</package>
+ package). This provides the ability to validate that all loaded types
+ are valid. Precisely what "valid" means depends on the context; the
+ default <classname>MetaModelValidator</classname> is a no-op. However,
+ some plug-in modules for <emphasis>Isis</emphasis> might provide their
+ own rules. For example, the <acronym>JPA</acronym> object store<footnote>
+ <para>Note that at the time of writing the JPA object store was part
+ of Isis, having originally been written as a sister project for the
+ Naked Objects framework.</para>
+ </footnote> requires that all domain objects that are annotated with
+ <classname>javax.jpa.Entity</classname> provide an "id" property
+ annotated with <classname>javax.jpa.Identifier</classname>. Or, you
+ might wish to configure your own
+ <classname>MetaModelValidator</classname> in order to enforce your own
+ project-specific rules.</para>
+
+ <para>The <classname>MetaModelValidator</classname> can be specified
+ using the <code>isis.reflector.validator</code> key. For example:</para>
+
+ <programlisting format="linespecific">isis.reflector.validator=com.mycompany.myproj.isis.MyMetaModelValidator</programlisting>
+
+ <para>will install
+ <classname>com.mycompany.myproj.isis.MyMetaModelValidator</classname> as
+ the <classname>MetaModelValidator</classname>.</para>
+ </sect1>
+
+ <sect1 id="sec.ProgrammingModelAPI">
+ <title><classname>ProgrammingModel</classname>
+ <acronym>API</acronym></title>
+
+ <para>As will be apparent from <xref
+ linkend="sec.HowTheMetaModelIsBuiltUpInternally" />, the set of
+ conventions that make up the programming model is determined by the set
+ of <classname>FacetFactory</classname>s that are used to process each
+ class as it is loaded by the
+ <classname>SpecificationLoader</classname>.</para>
+
+ <para>The <classname>ProgrammingModel</classname> (in the
+ <package>org.apache.isis.core.metamodel.progmodel</package> package)
+ class is used to define this set of
+ <classname>FacetFactory</classname>s, and is looked up right at the
+ beginning of the bootstrap process when the SpecificationLoader is being
+ specified. The default <classname>ProgrammingModel</classname> is
+ defined in the <emphasis>default progmodel</emphasis>
+ [oai.progmodels:dflt] module, and corresponds to the set of conventions
+ described in the applib documentation.</para>
+
+ <para>You may have occasion when you want to modify the
+ <classname>ProgrammingModel</classname>. For example, suppose you wanted
+ to support a new annotation, for example
+ <classname>@StringLengthBetween(3, 10)</classname> annotation intended
+ to be applied to string properties and parameters. This would require a
+ corresponding <classname>StringLengthBetweenFacetFactory</classname>.
+ This <classname>FacetFactory</classname> would then need to be added to
+ the <classname>ProgrammingModel</classname>.</para>
+
+ <para>There are two ways in which you can register this new
+ <classname>FacetFactory</classname>. The first is to create your own
+ <classname>ProgrammingModel</classname> (typically by subclassing the
+ default <classname>ProgrammingModel</classname>) and then call its
+ <methodname>#addFactory(Class<? extends
+ FacetFactory>)</methodname> method. Your new implementation should
+ then be registered in the isis.properties configuration file using the
+ <code>isis.reflector.facets</code> key:</para>
+
+ <programlisting format="linespecific">isis.reflector.facets=com.mycompany.myproj.isis.MyProgrammingModel</programlisting>
+
+ <para>will install
+ <classname>com.mycompany.myproj.isis.MyProgrammingModel</classname> as
+ the <classname>ProgrammingModel</classname>.</para>
+
+ <para>Alternatively, if you are just tweaking the default
+ <classname>ProgrammingModel</classname>, then you can simply use
+ <code>isis.reflector.facets.include</code> and
+ <code>isis.reflector.facets.exclude</code> keys to include/exclude
+ facets. The value for each of these keys is a comma-separated
+ list:</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=com.mycompany.myproj.isis.StringLengthBetweenFacetFactory,\
+ com.mycompany.myproj.isis.PositiveValuesOnlyFacetFactory</programlisting>
+
+ <para><note>
+ <para>Isis' support for Groovy works in this way; see the
+ <emphasis>progmodels</emphasis> <package>[oai:progmodels]</package>
+ documentation.</para>
+ </note></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title><emphasis>Metamodel</emphasis> Module
+ (<classname>ObjectAdapter</classname>s)</title>
+
+ <abstract>
+ <para>Second of two chapters concerning the classes and interfaces in
+ the <package>oai.core.metamodel</package> module, focusing on the
+ <classname>ObjectAdapter</classname> and related interfaces.</para>
+ </abstract>
+
+ <para>The previous chapter (<xref linkend="chp.MetaModel" />) provides an
+ overview of the package layering and dependencies for the <emphasis>core
+ metamodel</emphasis> module, along with a description of the
+ <classname>ObjectSpecification</classname> (cf
+ <classname>java.lang.Class</classname>) and related interfaces. This
+ chapter continues the coverage of this module, focusing on the
+ <classname>ObjectAdapter</classname> (cf
+ <classname>java.lang.Object</classname>) and related interfaces.</para>
+
+ <sect1 id="sec.ObjectAdapter">
+ <title><classname>ObjectAdapter</classname>s</title>
+
+ <para><emphasis>Isis</emphasis> wraps each domain object in an
+ <classname>ObjectAdapter</classname> (in the
+ <package>oai.core.metamodel.adapter</package> package). The rest of the
+ framework does not normally work with the domain objects directly, but
+ via these adapters. This is typically done by asking the
+ <classname>ObjectAdapter</classname> for its corresponding
+ <classname>ObjectSpecification</classname> by way of its
+ <methodname>#getSpecification()</methodname> method. This allows the
+ viewers to query the state of the object. For example the statement
+ <code>adapter.getSpecification().getProperties().get(0).get(adapter)</code>
+ would retrieve the first value of the first property of the domain
+ object held by the <emphasis>Isis</emphasis> referenced by
+ <code>adapter</code>.</para>
+
+ <para>The adapter also exposes facilities to allow the runtime to manage
+ the lifecycle of the wrapped domain object.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <methodname>#getOid()</methodname> method is used to
+ return a unique object identifier (an instance of the
+ <classname>Oid</classname> class in the
+ <package>org.apache.isis.core.metamodel.adapter.oid</package>
+ package)</para>
+
+ <para>This is an abstraction over a primary key, because it is
+ guaranteed to also be unique for non-persisted objects (if the
+ runtime supports non-persisted objects; the <emphasis>default
+ runtime</emphasis> does)</para>
+ </listitem>
+
+ <listitem>
+ <para>the <methodname>#getVersion()</methodname> returns version
+ information about the domain object through a
+ <classname>Version</classname> object</para>
+
+ <para>This allowing runtimes to implement optimistic locking</para>
+ </listitem>
+
+ <listitem>
+ <para>the #<methodname>getResolveState()</methodname> state
+ returning lazy loaded state, via the
+ <classname>ResolveSate</classname> object</para>
+
+ <para>This allows runtimes to know whether the datastore needs to be
+ queried to bring back additional data as the user "walks the object
+ graph".</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The <classname>Oid</classname> class in particular warrants
+ further discussion.</para>
+
+ <sect2>
+ <title>Object Identifiers (<classname>Oid</classname>s)</title>
+
+ <para>An <classname>Oid</classname> is an object identifier for every
+ domain entity, and is typically assigned by the runtime. For persisted
+ objects it is value is assigned by the object store, but for transient
+ objects (if the configured runtime supports them) the framework will
+ also assign an <classname>Oid</classname>, and will manage its
+ mutation if the object changes its persistence state (from transient
+ to persisted, or vice versa).</para>
+
+ <para>This <classname>Oid</classname> is used to uniquely reference
+ the same object either across space (client/server remoting calls
+ between VMs) or across time (between a sequence of requests to a
+ webapp, say). The <classname>Oid</classname> is unique and that means
+ that the runtime can maintain a one-to-one mapping to the
+ <classname>ObjectAdapter</classname>, and hence to the wrapped a
+ domain object.<note>
+ <para>Mapping the <classname>Oid</classname> to
+ <classname>ObjectAdapter</classname> is an example of the identity
+ map pattern. In the case of the <emphasis>default runtime
+ </emphasis><package>[oai.runtimes:dflt]</package>, the mapping is
+ actually both from <classname>Oid</classname> -->
+ <classname>ObjectAdapter</classname>, and from domain object pojo
+ --> <classname>ObjectAdapter</classname>. (The
+ <classname>ObjectAdapter</classname> has references to its
+ <classname>Oid</classname> and wrapped domain object pojo, so this
+ makes both of these implicitly bidirectional mappings).</para>
+ </note>Typically an <classname>Oid</classname> is also immutable,
+ however its value may change if an object changes its persistence
+ state. In this case the runtime is required to ensure that all
+ mappings that it might hold (eg from <classname>Oid</classname> to
+ <classname>ObjectAdapter</classname>) are correctly maintained. To
+ support this the previous state of the <classname>Oid</classname> is
+ copied so that <methodname>getPrevious()</methodname> now returns a
+ copy of the original <classname>Oid</classname> (instead of null) and
+ <methodname>hasPrevious()</methodname> will return
+ <code>true</code>.</para>
+
+ <note>
+ <para>This feature is used by the <emphasis>default
+ runtime</emphasis>'s [oai.runtimes:dflt] client/server remoting
+ module. When an <classname>Oid</classname> with a previous value is
+ persisted, the client-side runtime uses the previous
+ <classname>Oid</classname> to obtain the original tranisent object
+ from its local cache. The object is then removed from the cache, its
+ <classname>Oid</classname> is updated (via the
+ <methodname>copyFrom(Oid)</methodname> method) and then it is
+ returned to the cache. The results in the newly persisted object
+ having the new persistent <classname>Oid</classname> and it being
+ accessible as such from the cache. At this point the original
+ version's transient state will no longer be recognised.</para>
+ </note>
+
+ <sect3>
+ <title>Entity (owned) Collections</title>
+
+ <para>When an domain object is an entity that has a scalar reference
+ to another object (eg, an <classname>Order</classname> has an
+ associated <classname>Customer</classname>) then the referenced pojo
+ (<classname>Customer</classname>) will be wrapped in its own
+ <classname>ObjectAdapter</classname>. This is the usual, normal,
+ case, as described above.</para>
+
+ <para>When a domain object is an entity that has a vector reference
+ to another object (eg an <classname>Order</classname> has a
+ collection of <classname>OrderItem</classname>s), there is another
+ object to consider: the instance of
+ <classname>List<?></classname> (eg
+ <classname>ArrayList<OrderItem></classname>) that is "owned"
+ by the owning entity (<classname>Order</classname>).</para>
+
+ <para>An <classname>ObjectAdapter</classname> is created for this
+ owned <classname>List<?></classname> also, but its
+ <classname>Oid</classname> is of type
+ <classname>AggregatedOid</classname>, and its identity its kept
+ synchronized with its parent. This is done by way of the
+ <classname>AggregatedOid#getParentOid()</classname> method.</para>
+ </sect3>
+
+ <sect3>
+ <title>Values</title>
+
+ <para>Although values (such as <code>String</code>s, or
+ <code>int</code>s) are also wrapped in
+ <classname>ObjectAdapter</classname>, these always have a <code>null
+ </code><classname>Oid</classname>. Instead, the
+ <classname>ResolveState</classname> (as described in <xref
+ linkend="sec.ResolveState" />) is used to distinguish values and
+ deal with them appropriately.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Optimistic Locking (<classname>Version</classname>s)</title>
+
+ <para>In addition to an <classname>Oid</classname>, every
+ <classname>ObjectAdapter</classname> also references a
+ <classname>Version</classname> which represents the object at a
+ particular point in time. Calling
+ <methodname>ObjectAdapter#checkLock(Version)</methodname> allows the
+ adapter to check the <classname>Version</classname> it holds
+ internally against the provided <classname>Version</classname>; if
+ they are different then it will throw a
+ <classname>ConcurrencyException</classname>.</para>
+
+ <para>The <methodname>#checkVersion()</methodname> method is intended
+ to be called by server-side runtimes that either cache
+ <classname>ObjectAdapter</classname>s between calls (either
+ server-side in a <classname>HttpSession</classname>, say, or passed up
+ from a client-side runtime). The typical process is that the
+ server-side code will retrieve/recreate the cached object, and then
+ will compare it with the current version of the domain object as
+ retrieved from the database/object store. If there is a mismatch, then
+ the configured viewer is expected to handle the thrown exception, eg
+ by refreshing the view and prompting the user to retry.</para>
+ </sect2>
+
+ <sect2 id="sec.ResolveState">
+ <title>Lazy Loading (<classname>ResolveState</classname>)</title>
+
+ <para>The <classname>ResolveState</classname> class (in the
+ <package>org.apache.isis.core.metamodel.adapter</package> package) is
+ used by the <classname>ObjectAdapter</classname> to track the state of
+ the objects references by the underlying domain object. These states
+ form a state machine by which the framework can request to resolve
+ objects from the database/persistence mechanism if required.</para>
+
+ <para>The exact states available depend on the nature of the
+ <classname>ObjectAdapter</classname>, that is whether it represents a
+ regular domain entity, a value, or an owned collection
+ (<classname>List<?></classname>) of an entity:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>NEW - a short-lived state only applicable while figuring out
+ what type of object this is (value, transient or
+ persisted).</para>
+ </listitem>
+
+ <listitem>
+ <para>TRANSIENT - a not-yet persisted object. The corresponding
+ <classname>Oid</classname> of the
+ <classname>ObjectAdapter</classname> should also indicate that the
+ object is transient
+ (<methodname>Oid#isTransient()</methodname>).</para>
+ </listitem>
+
+ <listitem>
+ <para>GHOST - a persisted object whose state has not yet been
+ resolved (ie retrieved from the database/object store)</para>
+ </listitem>
+
+ <listitem>
+ <para>PART_RESOLVED - a persisted object whose properties are
+ resolved but some of the collections are not.</para>
+ </listitem>
+
+ <listitem>
+ <para>RESOLVED - a persisted object all of whose properties and
+ collections have been resolved</para>
+ </listitem>
+
+ <listitem>
+ <para>RESOLVING - a short-lived state on the way to RESOLVED; any
+ changes made to the object while in this state are ignored because
+ they are likely to be the result of an object store rehydrating
+ the object's properties/collections</para>
+ </listitem>
+
+ <listitem>
+ <para>RESOLVING_PART - a short-lived state on the way to
+ PART_RESOLVED; same rationale as RESOLVING</para>
+ </listitem>
+
+ <listitem>
+ <para>UPDATING - a short-lived state while the object is being
+ updated, eg as the result of invoking an action.</para>
+ </listitem>
+
+ <listitem>
+ <para>DESTROYED - a object that has now been removed from the
+ database and so is no longer considered persistent<footnote>
+ <para>The intent (at some stage) is to combine DESTROYED with
+ TRANSIENT, so the object simply switches from persisted and
+ not-persisted</para>
+ </footnote></para>
+ </listitem>
+
+ <listitem>
+ <para>SERIALIZING_GHOST, SERIALIZING_GHOST_PART_RESOLVED,
+ SERIALIZING_RESOLVED, SERIALIZING_TRANSIENT - states for the
+ adapter while it is being serialized, typically for remoting
+ purposes</para>
+ </listitem>
+
+ <listitem>
+ <para>VALUE - the state of a value (all other states relate to
+ entities or to entity collections)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The diagram below shows the state transitions supported by
+ <classname>ResolveState</classname>:</para>
+
+ <screenshot>
+ <screeninfo><classname>ResolveState</classname> state
+ transitions</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/metamodel/ResolveState-stateChart.png"
+ scale="60" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>In the case of the <emphasis>default runtime</emphasis>, the
+ transition between these states is typically managed by the bytecode
+ modules (cglib or javassist). These generate proxies that will
+ automatically trigger the resolving of properties/collections if
+ required (based on the <classname>ResolveState</classname>).</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Interacting with domain objects
+ (<classname>InteractionAdvisor</classname>)</title>
+
+ <para>One of the main responsibilities of the <emphasis>Isis</emphasis>
+ viewers is to interact with the domain objects and to render them in
+ generic (or customized) <acronym>OOUI</acronym>s. This involves an
+ interplay between the <classname>ObjectAdapter</classname> (that holds
+ the domain object) and the <classname>ObjectMember</classname>s
+ (<classname>OneToOneAssociation</classname>,
+ <classname>OneToManyAssociation</classname> and
+ <classname>ObjectAdapter</classname>) accessible from the
+ <classname>ObjectAdapter</classname>'s
+ <classname>ObjectSpecification</classname> (see <xref
+ linkend="sec.ObjectSpecifications" />).</para>
+
+ <para>The success or otherwise of this interaction is determined by the
+ Facets associated with the <classname>ObjectMember</classname>, and in
+ particular by those <classname>Facet</classname>s that implement
+ (sub-interfaces of) the <classname>InteractionAdvisor</classname>
+ interface:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>Facet</classname>s that implement
+ <classname>HidingInteractionAdvisor</classname> are used to
+ determine whether the <classname>ObjectMember</classname> is
+ visible.</para>
+
+ <para>If any <classname>Facet</classname> indicates that the member
+ is invisible, then the viewer should not display that member at
+ all.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>Facet</classname>s that implement
+ <classname>DisablingInteractionAdvisor</classname> are used to
+ determine whether the <classname>ObjectMember</classname> is
+ disabled.</para>
+
+ <para>If any <classname>Facet</classname> indicates that the member
+ is disable, then the viewer should disable (typically: grey out)
+ that member in the <acronym>UI</acronym>.</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>Facet</classname>s that implement
+ <classname>ValidatingInteractionAdvisor</classname> are used to
+ determine whether the proposed modification to/through the
+ <classname>ObjectMember</classname> is valid or not.</para>
+
+ <para>For a property, this means validating whether the proposed new
+ value for that property is valid, or if the request is to clear the
+ property, it means validating that the property may be set to
+ null.</para>
+
+ <para>For a collection, this means validating whether the proposed
+ object can be add to the collection (or removed from the
+ collection).</para>
+
+ <para>For an action, this means validating that each argument is
+ valid, and that the argument set as a whole is valid.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>It doesn't matter to the viewer whether the
+ <classname>Facet</classname> (that is,
+ <classname>InteractionAdvisor</classname>) vetoing the interaction is
+ because of an annotation (eg <classname>@MaxLength</classname>) or a
+ method call (eg <methodname>validatePlaceOrder(...)</methodname>), they
+ are all checked in the same way<footnote>
+ <para>The <classname>InteractionUtils</classname> class is used
+ internally by the <classname>ObjectMember</classname>s to check that
+ none of the Facets attached that are also
+ <classname>InteractionAdvisor</classname>s veto the request. This
+ can be a good place to add a breakpoint if you want to see Isis in
+ action at close quarters.</para>
+ </footnote>.</para>
+ </sect1>
+
+ <sect1 id="sec.RuntimeContext">
+ <title><classname>RuntimeContext</classname></title>
+
+ <para>The role of the <classname>RuntimeContext</classname> interface is
+ to decouple the metamodel from the configured runtime. It is primarily
+ used by the metamodel to obtain access to services provided by the
+ configured runtime. For example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>the <methodname>#getAdapterMap()</methodname> method is used
+ by the metamodel in order to create new
+ <classname>ObjectSpecification</classname>s (it is ultimately used
+ in <methodname>ObjectSpecification#createObject(...)</methodname>
+ and
+ <methodname>ObjectSpecification#createAggregatedObject(...)</methodname>;</para>
+ </listitem>
+
+ <listitem>
+ <para>the <methodname>#getQuerySubmitter()</methodname> method is
+ used by the metamodel within its implementation of
+ <classname>oai.applib.DomainObjectContainer</classname> (see <xref
+ linkend="sec.DomainObjectContainer" />) to support the
+ <methodname>#allMatches(...)</methodname> and
+ <methodname>#allInstances(...)</methodname> methods.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The metamodel provides a default implementation of
+ <classname>RuntimeContext</classname>, however this is a no-op and will
+ throw <classname>UnsupportedOperationException</classname>s in most
+ cases. The default runtime module's implementation is called
+ <classname>RuntimeContextFromSession</classname>, and provides access to
+ various services through the default runtimes service-locator
+ (<classname>IsisContext</classname>).</para>
+ </sect1>
+
+ <sect1 id="sec.DomainObjectContainer">
+ <title><classname>DomainObjectContainer</classname>
+ implementation</title>
+
+ <para>The <classname>oai.applib.DomainObjectContainer</classname>
+ interface represents the single point of coupling from domain objects to
+ the framework. Using <classname>DomainObjectContainer</classname>, a
+ domain object can do such things as create new objects, search for
+ existing objects, and raise warnings and such like.
+ <emphasis>Isis</emphasis> will automatically inject the
+ <classname>DomainObjectContainer</classname> into any entity that
+ provides a setter for it. (Inheriting from the
+ <classname>oai.applib.AbstractDomainObject</classname> is one easy way
+ to accomplish this, because it provides such as setter already).</para>
+
+ <para>The actual implementation of
+ <classname>DomainObjectContainer</classname> is provided by the
+ <emphasis>core metamodel</emphasis>, specifically by the
+ <classname>DomainObjectContainerDefault</classname> class (in
+ <package>oai.core.metamodel.services.container</package>). This
+ delegates off to various other parts of the framework as required. In
+ particular, it delegates to the configured runtime, by way of the
+ <classname>RuntimeContext</classname> interface (see <xref
+ linkend="sec.RuntimeContext" />).</para>
+ </sect1>
+
+ <sect1>
+ <title>Utilities</title>
+
+ <sect2>
+ <title>The Dump Utility</title>
+
+ <para>
<TRUNCATED>