isis-core.xml

<?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>&lt;dependencies&gt;
  &lt;dependency&gt;
    &lt;groupId&gt;org.apache.isis&lt;/groupId
    &lt;artifactId&gt;release&lt;/artifactId&gt;
    &lt;version&gt;x.x.x&lt;/version&gt;
    &lt;scope&gt;import&lt;/scope&gt;
  &lt;/dependency&gt;
  ...
&lt;/dependencies&gt;</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>&lt;dependencies&gt;
  &lt;dependency&gt;
    &lt;groupId&gt;org.apache.isis.core&lt;/groupId
    &lt;artifactId&gt;testsupport&lt;/artifactId&gt;
    &lt;version&gt;x.x.x&lt;/version&gt;
    <emphasis>&lt;scope&gt;test&lt;/scope&gt;</emphasis>
  &lt;/dependency&gt;
  ...
&lt;/dependencies&gt;</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&lt;ObjectAssociation&gt;)</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&lt;T&gt;</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&lt;? extends
      FacetFactory&gt;)</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> --&gt;
            <classname>ObjectAdapter</classname>, and from domain object pojo
            --&gt; <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&lt;?&gt;</classname> (eg
          <classname>ArrayList&lt;OrderItem&gt;</classname>) that is "owned"
          by the owning entity (<classname>Order</classname>).</para>

          <para>An <classname>ObjectAdapter</classname> is created for this
          owned <classname>List&lt;?&gt;</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&lt;?&gt;</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>The <classname>Dump</classname> class (in
        <package>oai.core.metamodel.util</package> package) provides a simple
        way out outputting the details of adapters and specifications.</para>

        <para>The <methodname>#specification(ObjectAdapter)</methodname> and
        <methodname>#specification(ObjectAdapter, DebugBuilder)</methodname>
        details the <classname>ObjectSpecification</classname> of the
        specified adapter:</para>

        <screen format="linespecific">Full Name: bom.Location
Short Name: Location
Plural Name: Locations
Singular Name: Location

Abstract: false
Lookup: false
Object: true
Value: false
Persistable: User Persistable
Superclass: java.lang.Object
Subclasses: empty
Interfaces: bom.Common
Fields
    OneToOneAssociationImpl@1408a92 [type=VALUE,id=type,label='Type',derived=false,type=Option]
    :
    :</screen>

        <para>The <methodname>#adapter(ObjectAdapter)</methodname> and
        <methodname>#adapter(ObjectAdapter, DebugBuilder)</methodname> methods
        detail the specified adapter:</para>

        <screen format="linespecific">Specification: bom.Location
Class: bom.Location
Adapter: org.apache.isis.object.defaults.PojoAdapter
Hash: #dada24
Title: test, Fort Worth
Object: bom.Location@18e4327
OID: OID#2F
State: ResolveState@1e1be92 [name=Resolved,code=PR]
Version: LongNumberVersion#1 20051118-025400170
Icon: null
Persistable: User Persistable</screen>

        <para>The <methodname>#graph(ObjectAdapter,
        AuthenticationSession)</methodname> and
        <methodname>#graph(ObjectAdapter, AuthenticationSession,
        DebugBuilder)</methodname> methods create a graph of the specified
        adapter, showing the wrapped object's associated objects and
        values:</para>

        <screen format="linespecific">PojoAdapter@dada24 [PR:OID#2F,specification=Location,version=LongNumberVersion#1 20051118-025400...
    +--type: POJO BusinessValueAdapter: One
    +--knownas: POJO TextStringAdapter: test
    +--streetaddress: POJO TextStringAdapter: address
    +--city: PojoAdapter@b51404 [PR:OID#C,specification=City,version=LongNumberVersion#1 ...
    |    +--name: POJO TextStringAdapter: Fort Worth
    +--customer: PojoAdapter@92dcdb [PR:OID#1C,specification=Customer,version=LongNumberVers...
    |    +--firstname: POJO TextStringAdapter: Richard
    |    +--lastname: POJO TextStringAdapter: Pawson
    |    +--phonenumbers: VectorCollectionAdapter@1d381d2 [PR:-,specification=Vector,version=...
    : 
    :</screen>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="chp.ProgModel">
    <title><emphasis>Progmodel</emphasis> Module</title>

    <abstract>
      <para>Classes and interfaces in the
      <package>oai.core.progmodel</package> module.</para>
    </abstract>

    <para>The core <emphasis>progmodel</emphasis> provides a set of reusable
    elements (implementations of the <classname>FacetFactory</classname>
    <acronym>API</acronym>) that can be reused to make up a programming model.
    These are brought together by implementations of the
    <classname>ProgrammingModel</classname> interface (in
    <package>oai.core.metamodel.progmodel</package> package, see <xref
    linkend="sec.ProgrammingModelAPI" />).</para>

    <para>The default programming model (as defined by the <emphasis>default
    progmodel</emphasis> module <package>[oai.progmodels:dflt]</package>)
    provides an implementation of <classname>ProgrammingModel</classname> that
    includes the vast majority of the <classname>FacetFactory</classname>s in
    this, the <emphasis>core progmodel</emphasis> module. However, we've
    chosen to separate these two modules because in the future we might want
    to implement new <classname>FacetFactory</classname>s, perhaps
    experimental, but not necessarily include them in the default programming
    model.</para>

    <para>The module also provides implementations of two other lesser
    <acronym>API</acronym>s; so let's look at the detail now.</para>

    <sect1>
      <title>Package Layering / Dependencies</title>

      <para>The packages that reside within <emphasis>core
      progmodel</emphasis> break into the following layers (top layer packages
      depending on lower layers):</para>

      <screenshot>
        <screeninfo>Architecture Diagram</screeninfo>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/progmodel/architecture-diagram.png"
                       scale="70" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>Alternatively we can see the actual dependencies between packages.
      Here we just focus on the subpackages of the <package>facets</package>
      package:</para>

      <screenshot>
        <screeninfo>Composition Diagram (facets package)</screeninfo>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/progmodel/composition-diagram-facets-package.png"
                       scale="80" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>As the diagrams show, most of the classes in the <emphasis>core
      progmodel</emphasis> module are implementations of the
      <classname>FacetFactory</classname> <acronym>API</acronym> (residing in
      the <package>oai.core.progmodel.facets</package> package). In addition,
      the package provides implementations of the
      <classname>FacetDecorator</classname> <acronym>API</acronym> (as
      discussed in <xref linkend="sec.FacetDecorator" />), the
      <classname>MemberLayoutArranger</classname><acronym> API</acronym> (see
      <xref linkend="sec.MemberLayoutArranger" />) and the
      <classname>MetaModelValidator</classname> <acronym>API</acronym> (see
      <xref linkend="sec.MetaModelValidator" />).</para>
    </sect1>

    <sect1>
      <title><classname>FacetFactory</classname> Implementations</title>

      <para>The <classname>FacetFactory</classname> implementations are by far
      the most significant part of programming model, both by volume and in
      terms of what they actually do. See <xref linkend="sec.FacetFactory" />
      for further discussion on <classname>FacetFactory</classname>
      interface.</para>

      <para>The implementations provided in <emphasis>core
      progmodel</emphasis> are broadly divided according to what they apply
      to:<itemizedlist>
          <listitem>
            <para>object-level</para>

            <para>If the object is an entity, then there are
            <classname>FacetFactory</classname>s to capture its title, its
            icon, its name and its description. There are also factories for
            an entity's lifecycle callbacks (eg the
            <methodname>created()</methodname> method) and the
            <methodname>validate()</methodname> callback.</para>

            <para>If the object is a value, then there are
            <classname>FacetFactory</classname>s for its value semantics (its
            default value, whether it is encodeable, whether it is parseable),
            and there are also <classname>FacetFactory</classname>s for
            String-based values to capture its mask, whether it is multi-line,
            and to capture regex pattern.</para>

            <para>For enum values, there is a factory to capture the choices
            of that enum (typically rendered as a drop-down list box)</para>

            <para>For objects that represent services there is a
            <classname>FacetFactory</classname> to capture whether the service
            is hidden.</para>

            <para>And finally, there are a number of factories that do not add
            any <classname>Facet</classname>s but that merely filter out
            methods. For example, the
            <classname>RemoveJavaLangObjectMethodsFacetFactory</classname>
            ensures that methods inherited from
            <classname>java.lang.Object</classname> (eg,
            <methodname>hashCode()</methodname>) are ignored. Methods
            annotated <classname>@Ignore</classname> are also ignored using
            the
            <classname>RemoveIgnoreAnnotationMethodsFacetFactory</classname>.</para>
          </listitem>

          <listitem>
            <para>object members</para>

            <para>The name and description can be specified explicitly (rather
            than inferred) for all object members, and so there are
            <classname>FacetFactory</classname>s for these.</para>

            <para>The hiding and disabling of members is also the same for all
            members, and so there are factories for these also.</para>

            <para>Finally, there is also a <classname>FacetFactory</classname>
            to pick up ordering metadata (the
            <classname>@MemberOrder</classname> annotation); this is used by
            the <classname>MemberOrderLayoutArranger</classname>
            implementations (see <xref
            linkend="sec.MemberLayoutArrangerImplementations" />).</para>
          </listitem>

          <listitem>
            <para>properties</para>

            <para>There are factories to locate each property's accessor,
            modify (regular setter or <methodname>modifyXxx()</methodname>
            method), clear (using <methodname>clearXxx()</methodname>
            method).</para>

            <para>Validation factories allow property validation by a variety
            of means (by <methodname>validateXxx()</methodname> method,
            mandatory by omission of <classname>@Optional</classname>
            annotation, mask, max length, per
            <methodname>@MustSatisfy</methodname> specification,
            regex).</para>

            <para>Choices and defaults for the property can be specified, as
            can whether the property is derived.</para>

            <para>Finally, there are <classname>FacetFactory</classname>s to
            provide rendering hints: multi-line, and typical length.</para>
          </listitem>

          <listitem>
            <para>collections</para>

            <para>Like properties, there are factories to locate each
            collections accessor, how it is modified (add/remove directory or
            using <methodname>addToXxx()</methodname> /
            <methodname>removeFromXxx()</methodname> methods) and how it is
            cleared. There is also a <classname>FacetFactory</classname> used
            to identify the type of element in the collection.</para>

            <para><classname>FacetFactory</classname>s to support validation
            are less extensive than those for properties, though: just to
            identify <methodname>validateAddToXxx()</methodname> /
            <methodname>validateRemoveFromXxx()</methodname> methods.</para>
          </listitem>

          <listitem>
            <para>actions</para>

            <para>The main factories for actions are to invoke it, and to
            validate its parameters (<methodname>validateXxx()</methodname>
            method).</para>

            <para>The other <classname>FacetFactory</classname>s are somewhat
            more specialized: to install <classname>Facet</classname>s that an
            action can only be invoked in exploration mode, or in prototype
            mode, or when a viewer-specific debug "gesture" is performed (eg
            ctrl-shift-click). There is also a factory to capture the "execute
            on" location (for client/server deployments).</para>

            <para>For actions on services, there are factories to indicate
            that it is not contributed, or that it should not appear in the
            service menu.</para>
          </listitem>

          <listitem>
            <para>action parameters</para>

            <para>The <classname>FacetFactory</classname>s for action
            parameters are very similar to those for properties.</para>

            <para>First, there are factories for each parameters name, and
            description (provided for all object members)</para>

            <para>Then, there are factories fo validation (by
            <methodname>validateXxx()</methodname> method, mandatory by
            omission of <classname>@Optional</classname>, mask, max length,
            per <methodname>@MustSatisfy</methodname> specification,
            regex)</para>

            <para>Choices and defaults also have their own factories.</para>

            <para>And finally, there are <classname>FacetFactory</classname>s
            for rendering hints: multi-line and typical length.</para>
          </listitem>
        </itemizedlist></para>

      <para>As already indicated, pretty much all of the above-listed
      <classname>FacetFactory</classname>s are included in the
      <emphasis>default programming</emphasis> model
      <package>[oai.progmodels:dflt]</package>, and correspond more-or-less to
      the programming conventions described in the AppLib documentation
      <package>[oai:applib]</package>.</para>
    </sect1>

    <sect1>
      <title><classname>FacetDecorator</classname> Implementations</title>

      <note>
        <para>As was noted in <xref linkend="sec.FacetDecorator" />, 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> API 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>

      <note>
        <para>Only one FacetDecorator is documented here. At the time of
        writing there is, in fact, another FacetDecorator which is used for
        adding help. However, it's not clear that it actually does anything,
        and in any case ought to be implemented as a FacetFactory. A ticket
        has been raised, see <ulink
        url="https://issues.apache.org/jira/browse/ISIS-85">ISIS-85</ulink> in
        JIRA.</para>
      </note>

      <sect2>
        <title>Internationalization (I18n) Decorator</title>

        <para>The <classname>I18nFacetDecorator</classname> allows names,
        descriptions and help text to be replaced with internationalized
        versions. It uses Java's built-in
        <classname>java.util.ResourceBundle</classname> mechanism to
        accomplish this, using a key based on each class member.</para>

        <para>For example, the following fragment is part of one of those
        translation files:</para>

        <programlisting format="linespecific">com.mycompany.myapp.dom.Contact.property.Phone.name=Téléphone
com.mycompany.myapp.dom.Contact.property.FullName.description=Le nom complet du client
com.mycompany.myapp.dom.Contact.action.CreatePhone.name=Nouveau téléphone
com.mycompany.myapp.dom.Contact.action.CreatePhone.description=Créez un nouveau téléphone et ajoutez-le au contact actuel
com.mycompany.myapp.dom.Contact.action.CreatePhone.parameter1.name=Indicatif de zone
com.mycompany.myapp.dom.Contact.action.CreatePhone.parameter2.name=Nombre</programlisting>

        <para>The following shows the translated action name and description,
        and two parameter names being specified for the action
        <emphasis>createPhone</emphasis>, which is defined by the
        <methodname>createPhone</methodname> method.</para>

        <sect3>
          <title>Configuration</title>

          <para>To configure the decorator, add the following to
          <filename>isis.properties</filename> configuration file:</para>

          <programlisting format="linespecific">isis.reflector.facet-decorators=resource-i18n</programlisting>

          <para>Then, add <classname>ResourceBundle</classname> files, as
          described in the next section.</para>
        </sect3>

        <sect3>
          <title><classname>ResourceBundle</classname> File Location</title>

          <para>If the application is being accessed via a webapp, then the
          server performs the localisation. If running in client/server mode
          (in the the <emphasis>default runtime</emphasis>,
          <package>[oai.runtimes:dflt]</package>), then the localization will
          be perfomed by the client. Whichever tier performs the localization
          will require the <classname>ResourceBundle</classname> files to be
          on its classpath.</para>

          <note>
            <para>The AppLib now supports a Localization interface. It would
            be better to localize with respect to this interface, see <ulink
            url="https://issues.apache.org/jira/browse/ISIS-86">ISIS-86</ulink>
            in JIRA.</para>
          </note>

          <para>Translated names, descriptions and help text for a specific
          language should be held in a file named in the following
          format:</para>

          <programlisting>i18n_&lt;language code&gt;_&lt;country code&gt;.properties</programlisting>

          <para>The language and country codes must reflect the translated
          language are ISO standards.</para>

          <para>These files must be on the root of the class path, typically
          in <filename>src/main/resources</filename>. For example:</para>

          <screen format="linespecific">src/main/resources/
   <emphasis role="strong">i18n_en_GB.properties
   i18n_de_DE.properties
   i18n_fr_FR.properties</emphasis>
   </screen>

          <para>where <filename class="directory"
          moreinfo="none">i18n_en_GB.properties</filename> is the file for
          English in Great Britain, fr_FR is for French in France, and so
          on.</para>
        </sect3>

        <sect3>
          <title><classname>ResourceBundle</classname> File Contents</title>

          <para><classname>ResourceBundle</classname> files are key/value
          pairs, where the key is unique and the value is the
          internationalized text. The
          <classname>I18nFacetDecorator</classname> requires that the keys
          follow the following conventions.</para>

          <para>Each property can have a line for each of the name,
          description and help text. The format for properties is:</para>

          <programlisting format="linespecific">&lt;fully.qualified.ClassName&gt;.property.&lt;PropertyName&gt;.name=&lt;translated name&gt;
&lt;fully.qualified.ClassName&gt;.property.&lt;PropertyName&gt;.description=&lt;translated description&gt;
&lt;fully.qualified.ClassName&gt;.property.&lt;PropertyName&gt;.help=&lt;translated help&gt;</programlisting>

          <para>while the format for collections, not surprisingly, is:</para>

          <programlisting format="linespecific">&lt;fully.qualified.ClassName&gt;.collection.&lt;CollectionName&gt;.name=&lt;translated name&gt;
&lt;fully.qualified.ClassName&gt;.collection.&lt;CollectionName&gt;.description=&lt;translated description&gt;
&lt;fully.qualified.ClassName&gt;.collection.&lt;CollectionName&gt;.help=&lt;translated help&gt;</programlisting>

          <para>The class name must be fully qualified and the
          property/collection name is the short name provided by the
          metamodel. All the values are case sensitive.</para>

          <para>Actions are specified in a similar fashion to properties and
          collections but with the keyword <emphasis>action</emphasis> instead
          of <emphasis>property</emphasis>. Parameters within an action can
          also be translated by inserting <emphasis>parameter</emphasis> and a
          number before the keyword. Each parameter must be numbered to show
          its position, starting from one (1), eg
          <emphasis>parameter1</emphasis>, <emphasis>parameter2</emphasis>
          etc.</para>

          <programlisting format="linespecific">&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.name=&lt;translated name&gt;
&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.description=&lt;translated description&gt;
&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.help=&lt;translated help&gt;

&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.parameter&lt;index&gt;.name=&lt;translated name&gt;
&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.parameter&lt;index&gt;.description=&lt;translated description&gt;
&lt;fully.qualified.ClassName&gt;.action.&lt;ActionName&gt;.parameter&lt;index&gt;.help=&lt;translated help&gt;</programlisting>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="sec.MemberLayoutArrangerImplementations">
      <title><classname>MemberLayoutArranger</classname>
      Implementations</title>

      <para>There <emphasis>core progmodel</emphasis> module provides three
      implementations of the <classname>MemberLayoutArranger</classname>
      <acronym>API</acronym>:</para>

      <itemizedlist>
        <listitem>
          <para><classname>MemberLayoutArrangerUsingOrderMethod</classname>,
          which orders members according to the static
          <methodname>fieldOrder()</methodname> and
          <methodname>actionOrder()</methodname> sort methods</para>
        </listitem>

        <listitem>
          <para><classname>MemberLayoutArrangerUsingMemberOrderFacet</classname>,
          which orders members according to the
          <classname>@MemberOrder</classname> annotation</para>
        </listitem>

        <listitem>
          <para><classname>MemberLayoutArrangerDefault</classname> (in the
          <package>org.apache.isis.core.progmodel.layout.dflt</package>
          package), a composite that delegates to first to
          <classname>MemberLayoutArrangerUsingOrderMethod</classname> and then
          to
          <classname>MemberLayoutArrangerUsingMemberOrderFacet</classname>.</para>
        </listitem>
      </itemizedlist>

      <para>As its name suggest, the last of these is the default. A different
      implementation can be specified if required, see <xref
      linkend="sec.MemberLayoutArranger" />.</para>
    </sect1>

    <sect1>
      <title><classname>MetaModelValidator</classname> Implementation</title>

      <para>The core progmodel module provides a single implementation of
      <classname>MetaModelValidator</classname> <acronym>API</acronym>, namely
      <classname>MetaModelValidatorDefault</classname> (in the
      <classname>org.apache.isis.core.progmodel.metamodelvalidator.dflt</classname>
      package). This implementation is actually a no-op; that is it enforces
      no additional rules and will always successfully validate the
      metamodel.</para>

      <para>Different implementations can be specified if required, see <xref
      linkend="sec.MetaModelValidator" />. The
      <classname>MetaModelValidatorComposite</classname> adapter class (in
      <package>org.apache.isis.core.metamodel.specloader.validator</package>
      package) can be used to combine distinct validator implementations if
      required.</para>
    </sect1>
  </chapter>

  <chapter id="chp.Runtime">
    <title><emphasis>Runtime</emphasis> Module</title>

    <abstract>
      <para>Classes and interfaces in the <package>oai.core.runtime</package>
      module.</para>
    </abstract>

    <para>The <emphasis>core runtime</emphasis>
    <package>[oai.core:runtime]</package> module (not to be confused with the
    <emphasis>default runtime</emphasis> module,
    <package>[oai.runtimes:dflt]</package>) defines a number of
    <acronym>API</acronym>s and provides supporting classes that are likely to
    be of use by most runtime implementations. Most significant of these
    <acronym>API</acronym>s is the security (authentication and authorization)
    <acronym>API</acronym>, but there are one or two lesser APIs also.</para>

    <note>
      <para>At the time of writing there is only one major runtime
      implementation, the aforementioned <emphasis>default runtime</emphasis>
      module <package>[oai.runtimes:dflt]</package>. However, in the future
      there may be other runtimes also. The intent is for reusable
      functionality from the <emphasis>default runtime</emphasis> to be moved
      up to the <emphasis>core runtime</emphasis>. However, one aspect that we
      intend to remain in the default runtime is the
      <classname>IsisContext</classname> service locator pattern (because we
      expect to use JSR-292-style <acronym>CDI</acronym>/dependency injection)
      for newer runtimes. Any functionality to move up to the core runtime
      will therefore need to remove any dependency on
      <classname>IsisContext</classname>.</para>
    </note>

    <sect1>
      <title>Package Layering / Dependencies</title>

      <para>The packages that reside within <emphasis>core runtime</emphasis>
      break into the following layers (top layer packages depending on lower
      layers):</para>

      <screenshot>
        <screeninfo>Architecture Diagram</screeninfo>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/runtime/architecture-diagram.png"
                       scale="70" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>As the diagram show, the classes in the <emphasis>core
      runtime</emphasis> module relate either to authentication,
      authorization, image loading or the snapshot facility. Let's look at
      each in turn.</para>
    </sect1>

    <sect1>
      <title>Authentication (<classname>AuthenticationManager</classname>
      <acronym>API</acronym>)</title>

      <para>The <package>oai.core.runtime.authentication</package> package
      provides an <classname>AuthenticationManagerInstaller</classname> (see
      <xref linkend="sec.ComponentAndInstallerApi" /> for details on the
      <classname>Installer</classname> <acronym>API</acronym>) which acts as a
      factory for an <classname>AuthenticationManager</classname>. As you
      might expect, this component can be used to authenticate users, using a
      user/password check. The actual mechanism to obtain the
      <classname>AuthenticationManager</classname> depends upon the configured
      runtime (for example the <emphasis>default runtime</emphasis>
      <package>[oai.runtimes:dflt]</package> makes it available through its
      <classname>IsisContext</classname> service locator).</para>

      <para>The <emphasis>core runtime</emphasis> also provides a "standard"
      implementation, <classname>AuthenticationManagerStandard</classname>.
      This defines a sub-<acronym>API</acronym>,
      <classname>Authenticator</classname>, which reduces the responsibilities
      down to a small number of methods, including
      <methodname>#authentication(AuthenticationRequest)</methodname>, and
      returning an <classname>AuthenticationSession</classname> (as defined in
      <xref linkend="sec.AuthenticationSession" />). The standard
      implementation also assigns a unique session key to all currently
      authenticated users, which can be used to check if a given
      <classname>AuthenticationSession</classname> is valid.</para>

      <para>If using the <emphasis>default runtime</emphasis>, the
      authentication mechanism is specified using
      <filename>isis.properties</filename> configuration file:</para>

      <para><programlisting>isis.authentication=xxx</programlisting>where
      "xxx" is the name provided by implementation of
      <classname>AuthenticationManagerInstaller</classname>.</para>

      <para>The actual implementations of security can be found in the
      security modules implementations, that is child modules of
      <package>[oai:security]</package>. For example, the file-based
      authentication manager is specified by
      <classname>FileAuthenticationManagerInstaller</classname> (in the
      <package>[oai.security:file]</package> module); and can be specified
      using:</para>

      <programlisting>isis.authentication=file</programlisting>
    </sect1>

    <sect1>
      <title>Authorization (<classname>AuthorizationManager</classname>
      <acronym>API</acronym>)</title>

      <para>The <package>oai.core.runtime.authorization</package> package is
      entirely analogous to authentication, providing an
      <classname>AuthorizationManagerInstaller</classname> API which acts as a
      factory for an <classname>AuthorizationManager</classname>. This
      component is used to enable/disable access to class members (properties,
      collections and actions). Specifically, a class member can be hidden
      (through the
      <methodname>AuthorizationManager#isVisible(...)</methodname> method), or
      may be visible but disabled (through the
      <methodname>AuthorizationManager#isUsable(...)</methodname>
      method).</para>

      <para>Again like authentication, the <emphasis>core runtime</emphasis>
      provides a "standard" implementaion,
      <classname>AuthorizationManagerStandard</classname>, which in turn
      defines a sub-<acronym>API</acronym>, <classname>Authorizor</classname>.
      This simplies the <acronym>API</acronym> for authorization down to two
      methods: isVisibleInRole(...) and
      <classname>isUsableInRole(...)</classname>.</para>

      <para>If using the <emphasis>default runtime</emphasis>, the
      authorization mechanism is specified using
      <filename>isis.properties</filename> configuration file:</para>

      <para><programlisting>isis.authorization=xxx</programlisting>where "xxx"
      is the name provided by implementation of
      <classname>AuthorizationManagerInstaller</classname>.</para>

      <para>The actual implementations of security can be found in the
      security modules implementations, that is child modules of
      <package>[oai:security]</package>. For example, the file-based
      authorization manager is specified by
      <classname>FileAuthorizationManagerInstaller</classname> (in the
      <package>[oai.security:file]</package> module); and can be specified
      using:</para>

      <programlisting>isis.authorization=file</programlisting>
    </sect1>

    <sect1>
      <title>(Client) Image Loading
      (<classname>TemplateImageLoader</classname>
      <acronym>API</acronym>)</title>

      <para>The <classname>TemplateImageLoader</classname> API is a minor
      <acronym>API</acronym> used by client-side applications for loading
      <classname>java.awt.Image</classname>s from the classpath or from files.
      Two of its uses are to render the initial splash window, and to load
      images and icons for the <emphasis>DnD</emphasis> viewer.</para>

      <para>Viewers are not compelled to use this <acronym>API</acronym>, and
      indeed the web-based viewers tend to use their own mechanism.</para>

      <para><note>
          <para>It's not clear that this <acronym>API</acronym> is really
          significant enough to be factored out. It may be better to just
          duplicate the code for the splash window and move the main
          implementation to the <emphasis>DnD</emphasis> viewer.</para>
        </note></para>

      <para>There are a number of generic images that are used by the
      framework, and that can be changed to create a different look. These
      are:</para>

      <itemizedlist>
        <listitem>
          <para><literal>empty-field.png</literal></para>
        </listitem>

        <listitem>
          <para><literal>logo.jpg</literal></para>
        </listitem>

        <listitem>
          <para><literal>small-logo.png</literal></para>
        </listitem>

        <listitem>
          <para><literal>transient.png</literal></para>
        </listitem>

        <listitem>
          <para><literal>unknown.png</literal></para>
        </listitem>
      </itemizedlist>

      <sect2>
        <title>Typical Usage by Viewers</title>

        <para>Typically viewers ae expected to load images for viewers based
        on the domain object's class, following the convention <filename
        class="directory"
        moreinfo="none">&lt;ClassName&gt;.&lt;extension</filename>&gt;, but in
        general corresponding to the value returned by the
        <classname>IconFacet</classname> facet:</para>

        <itemizedlist>
          <listitem>
            <para>This will be case sensitive on Unix/Linux, but case
            insensitive on Windows:</para>
          </listitem>

          <listitem>
            <para>It is the viewer's responsibility to specify which
            extensions are supported; typically all of <filename
            class="directory" moreinfo="none">.gif</filename>, <filename
            class="directory" moreinfo="none">.png</filename>, <filename
            class="directory" moreinfo="none">.jpg</filename> and <filename
            class="directory" moreinfo="none">.jpeg</filename> would be
            supported.</para>
          </listitem>

          <listitem>
            <para>It is the viewer's responsibility to specify the form of the
            class name; typically both the short form or the fully qualified
            name of the class would be supported.</para>
          </listitem>

          <listitem>
            <para>When loading images based on class, if no image is found for
            the current class then the process is repeated using the name of
            the class's immediate superclass. This process repeats until there
            are no more superclasses.</para>
          </listitem>
        </itemizedlist>
      </sect2>
    </sect1>

    <sect1>
      <title>Snapshot</title>

      <para>The <package>oai.core.runtime.snapshot</package> package provides
      the <classname>XmlSnapshot</classname> utility class. This is not used
      by the framework itself; rather it is provided as the basis for domain
      services (called by domain objects) that wish to generate
      <acronym>XML</acronym> representations of a domain object or a graph of
      domain objects.</para>

      <para>The functionality was originally developed to support the
      generation of <acronym>PDF</acronym> form letters using
      <acronym>XML</acronym> and <acronym>XSD</acronym>s, but has since been
      used for the generation of other communication types (such as emails and
      <acronym>SMS</acronym>) as well as a means to publish
      <acronym>XML</acronym> domain events to an enterprise service
      bus.</para>

      <para>The XmlSnapshot Javadoc summarises how to use the class:</para>

      <programlisting>XmlSnapshot snapshot = new XmlSnapshot(customerAdapter);  // (1) 
Element customerAsXml = snapshot.toXml(); // (2)
snapshot.include("placeOfBirth");   // (3) 
snapshot.include("orders/product"); // (4)
Element customerAsXml2 = snapshot.toXml(); // (5)</programlisting>

      <para>where:</para>

      <itemizedlist>
        <listitem>
          <para>(1) <code>customerAdapter</code> is a reference to an
          <classname>ObjectAdapter</classname> (see <xref
          linkend="sec.ObjectAdapter" />).</para>
        </listitem>

        <listitem>
          <para>(2) returns customer's fields, titles of simple references,
          number of items in collections</para>
        </listitem>

        <listitem>
          <para>(3) specify that the snapshot should also navigate to all
          "orders" of Customer, and from them to their "product"s</para>
        </listitem>

        <listitem>
          <para>(4) specify that the snapshot should also navigate to another
          object represented by simple reference "placeOfBirth"</para>
        </listitem>

        <listitem>
          <para>(5) returns the new snapshot, including the specified
          navigations from (3) and (4)</para>
        </listitem>
      </itemizedlist>

      <para>In order to make the functionality available through a domain
      service, the service will need to convert a domain object pojo into an
      <classname>ObjectAdapter</classname>. The precise mechanism for doing
      this will depend on the configured runtime; if using the
      <emphasis>default runtime
      </emphasis><package>[oai.runtimes:dflt]</package> then this can be done
      through the <classname>IsisContext</classname> service locator. The
      default runtime further simplifies snapshot creation through its
      <classname>XmlSnapshotBuilder</classname>:</para>

      <para><programlisting> XmlSnapshot snapshot = XmlSnapshotBuilder.create(customerPojo)
                            .includePath("placeOfBirth")
                            .includePath("orders/product")
                            .build();
Element customerAsXml = snapshot.toXml(); </programlisting></para>

      <para>A domain service for generating snapshots might therefore have the
      following interface:</para>

      <programlisting>public interface XmlSnapshotService {
    public Element snapshot(Object pojo, String... includePaths);
}</programlisting>

      <para>and would be implemented as:</para>

      <programlisting>public class XmlSnapshotServiceUsingDefaultRuntime implements XmlSnapshotService {
    public Element snapshot(Object pojo, String... includePaths) {
        XmlSnapshotBuilder builder = XmlSnapshotBuilder.create(pojo);
        for(String includePath: includePaths) {
            builder.includePath(includePath);
        }
        return builder.build().toXml();
    }
}</programlisting>
    </sect1>

    <sect1>
      <title>Command Line Flag (<classname>OptionHandler</classname>)
      API</title>

      <para>The
      <classname>oai.core.runtime.optionhandler.OptionHandler</classname>
      <acronym>API</acronym> is a mechanism to allow runtimes to write command
      line launchers that use the <ulink
      url="http://commons.apache.org/cli">Apache Commons CLI</ulink>
      <acronym>API</acronym> for specifying command line flags.</para>

      <para>The <classname>OptionHandler</classname> interface extends from
      <classname>IsisConfigurationBuilderPrimer</classname>, meaning that each
      instance is handed an <classname>IsisConfigurationBuilder</classname> in
      order to add additional configuration properties. For example, the
      <emphasis>default runtime</emphasis> defines a
      <classname>OptionHandlerViewer</classname> which searches for the
      <code>--viewer</code> flag and loads the relevant properties file (eg
      <filename>viewer_html.properties</filename> if
      <code>--viewer=html</code> is specified).</para>

      <para>The mechanism to register <classname>OptionHandler</classname>s is
      specific to each runtime implemenetation. For example, the default
      runtime has an <classname>IsisRunner</classname> class which defines an
      <methodname>addOptionHandler(...)</methodname> method.</para>
    </sect1>

    <sect1>
      <title>User Profiles</title>

      <para>The idea behind user profiles is to allow viewers to store
      information about a user, for example as their preferences, bookmarks
      and other related information. The applib itself already defines the
      <classname>oai.applib.profiles.Profile</classname> interface to (which
      represent an end-user's profile), and the
      <classname>oai.applib.profiles.Perspective</classname> (which represents
      an end-users' desktop perspective; that is icons/links for domain
      services and domain objects). The
      <classname>oai.core.runtime.userprofile</classname> package provides a
      set of classes to allow runtimes to provide an implementation of these
      applib interfaces:</para>

      <itemizedlist>
        <listitem>
          <para>The <classname>UserProfile</classname> class is intended to
          assist the implementation of
          <classname>oai.applib.profiles.Profile</classname> interface. It
          holds a reference to an <classname>Options</classname> object , an
          collection of <classname>PerspectiveEntry</classname> objects (both
          in <package>oai.core.runtime.userprofile</package> package, and
          discussed below), and an <classname>oai.applib.profiles.
          Localization</classname> object (to represent the user's current
          locale)</para>
        </listitem>

        <listitem>
          <para>The <classname>Options</classname> class is a wrapper around a
          <classname>java.util.Properties</classname> object, and allows the
          viewer to store a collection of settings for the user. Options can
          also be nested (that is, an <classname>Option</classname> can hold
          another as one of its keys).</para>
        </listitem>

        <listitem>
          <para>The <classname>PerspectiveEntry</classname> class is intended
          to assist in the implementation of
          <classname>oai.applib.profiles.Perspective</classname> interface,
          representing a saved view representation within the viewer. A
          <classname>PerspectiveEntry</classname> has a name, has a 'service'
          collection of objects, and an 'objects' collection.</para>
        </listitem>
      </itemizedlist>

      <para>The <package>userprofile</package> package also defines the
      <classname>UserProfileStore</classname> and
      <classname>UserProfileLoader</classname> interfaces. These are suggested
      <acronym>API</acronym>s for runtimes to implement, indicating a
      mechanism by which viewers can have a consistent way to obtain
      <classname>UserProfile</classname>s, irrespective of the configured
      runtime in use. For example, the default runtime
      <package>(oai.runtimes:dflt)</package> makes the
      <classname>UserProfileStore</classname> available through its
      <classname>IsisContext</classname> service locator.</para>

      <para>The mechanism to specify the profile store to use depends on the
      configured runtime. The <emphasis>default runtime</emphasis>
      <package>(oai.runtimes:dflt)</package>, for example, allows the profile
      store to be specified using a property in
      <filename>isis.properties</filename> configuration file:</para>

      <programlisting>isis.user-profile-store=xml</programlisting>

      <para>Alternatively a command line flag (-e or --user-profile-store) can
      be used.</para>

      <para>If a non-persisting profile store is specified, then the profile
      will simply be kept in memory, and lost on exit.</para>
    </sect1>

    <sect1>
      <title>Utility Classes</title>

      <sect2>
        <title>Sysout (SystemPrinter) Utility</title>

        <para>The <classname>oai.core.runtime.sysout.SystemPrinter</classname>
        utility is a simple wrapper to make it easy to print to any
        <classname>java.io.Outputstream</classname> (defaulting to
        <code>System.out</code>). It also includes a number of methods for
        printing out the version of <emphasis>Isis</emphasis>.</para>
      </sect2>

      <sect2>
        <title>Profiler Utility</title>

        <para>The <classname>oai.core.runtime.profiler.Profiler</classname>
        class provides simple support for diagnosing timing and memory issues.
        It allows the memory snapshots and timing to be captured on a per
        thread basis, so that, for example, any memory leaks can be tracked by
        snapshotting at the beginning or end of requests.</para>
      </sect2>
    </sect1>

    <sect1>
      <title>Logging Support</title>

      <sect2>
        <title>Log4J snapshot appenders</title>

        <para><emphasis>Apache Isis</emphasis> uses <ulink
        url="http://logging.apache.org">Apache log4j</ulink> as its mechanism,
        and provides a number of log4j appender implementations which can be
        used in your application if you require.</para>

        <para>Specifically, the framework provides a number of appenders that
        create a snapshot of the recently logged events instead of capturing
        all events since the system started. The benefits here are
        twofold:<itemizedlist>
            <listitem>
              <para>First, writing to the appenders is minimised as they are
              only written when errors occur or the user demands it.</para>
            </listitem>

            <listitem>
              <para>Second, the partial log can be automatically sent over the
              network to someone who needs to know when things have gone
              wrong.</para>
            </listitem>
          </itemizedlist></para>

        <para>All the snapshot appends support the same basic
        properties:-</para>

        <itemizedlist>
          <listitem>
            <para><emphasis> <methodname>addInfo</methodname>
            </emphasis></para>

            <para>(boolean) indicates whether to prepend details about the
            machine, os and Java to log, eg</para>

            <programlisting format="linespecific">Snapshot:- Thu Dec 01 14:34:24 GMT 2005
  R Matthews
  Windows XP (x86) 5.1
  Java HotSpot(TM) Client VM 1.4.2_04-b05
  Version  000000</programlisting>
          </listitem>

          <listitem>
            <para><emphasis> <methodname>bufferSize</methodname>
            </emphasis></para>

            <para>(integer) the number of events to write out to the snapshot.
            Defaults to 512 events.</para>
          </listitem>

          <listitem>
            <para><emphasis> <methodname>locationInfo</methodname>
            </emphasis></para>

            <para>(boolean) whether to capture the details of where in the
            code the event was generated. Note - capturing this information
            can be quite expensive.</para>
          </listitem>

          <listitem>
            <para><emphasis> <methodname>evaluatorClass</methodname>
            </emphasis></para>

            <para>(<classname>org.apache.log4j.spi.TriggeringEventEvaluator</classname>)
            a trigger that determines when a snapshot should be created. The
            trigger object is given each event that is logged and flags when
            to produce a snapsho.</para>

            <para>When not trigger is specified a default trigger is applied
            that triggers a snapshot when an event of level ERROR or FATAL
            occurs.</para>
          </listitem>
        </itemizedlist>

        <sect3>
          <title>File snapshot appender</title>

          <para>The <classname>FileSnapshotAppender</classname> writes the
          snapshot to timestamped file. The following properties can be
          specified:-</para>

          <itemizedlist>
            <listitem>
              <para><emphasis><methodname>directory</methodname></emphasis></para>

              <para>The directory path where the files are to be created. If
              none is specified then the working directory will be
              used.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>extension</methodname></emphasis></para>

              <para>The extension type to append to the file name.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>fileName</methodname></emphasis></para>

              <para>The base name of the log file, which will have timestamp
              appended. Defaults to 'log-snapshot-'.</para>
            </listitem>
          </itemizedlist>

          <para>The following example writes xml snapshots to the logs
          directory to files ending with '.xml'.</para>

          <programlisting format="linespecific">log4j.appender.Snapshot=org.apache.isis.core.runtime.logging.FileSnapshotAppender
log4j.appender.Snapshot.bufferSize=1024
log4j.appender.Snapshot.addInfo=true
log4j.appender.Snapshot.locationInfo=true
log4j.appender.Snapshot.directory=logs
log4j.appender.Snapshot.extension=xml
log4j.appender.Snapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>
        </sect3>

        <sect3>
          <title>Popup snapshot appender</title>

          <para>The <classname>PopupSnapshotAppender</classname> displays a
          popup dialog showing the snapshot. Do not use this on a server as
          there will be no one sitting in front of it to see it. It has no
          properties so its configuration is short.</para>

          <programlisting format="linespecific">log4j.appender.Popup=org.apache.isis.core.runtime.logging.PopupSnapshotAppender
log4j.appender.Popup.layout=org.apache.log4j.PatternLayout
log4j.appender.Popup.layout.ConversionPattern=%-5r [%-20c{1} %-10t %-5p]  %m%n
</programlisting>
        </sect3>

        <sect3>
          <title>Email snapshot appender</title>

          <para>The <classname>SmtpSnapshotAppender</classname> generates an
          email with the snapshot in it and sends it to a specified recipient.
          The following properties can be specified:-</para>

          <itemizedlist>
            <listitem>
              <para><emphasis><methodname>server</methodname></emphasis></para>

              <para>Address of the email server</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>port</methodname></emphasis></para>

              <para>The port the server listen on for SMTP requests. Defaults
              to port 25.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>recipient</methodname></emphasis></para>

              <para>Email address to send the snapshot to.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>domain</methodname></emphasis></para>

              <para>The address that client connects to the server with. Some
              email servers validate the sender's address in the MAIL FROM
              command so you may need to specify a real address here.</para>
            </listitem>
          </itemizedlist>

          <para>The following example sends a short <acronym>HTML</acronym>
          snapshot logs to logs@support.acme.com, via the email server at
          my.emailserver.com using port 25.</para>

          <programlisting format="linespecific">log4j.appender.EmailSnapshot=org.apache.isis.core.runtime.logging.SmtpSnapshotAppender
log4j.appender.EmailSnapshot.bufferSize=50
log4j.appender.EmailSnapshot.addInfo=true
log4j.appender.EmailSnapshot.server=my.emailserver.com
log4j.appender.EmailSnapshot.port=25
log4j.appender.EmailSnapshot.recipient=logs@support.acme.com
log4j.appender.EmailSnapshot.layout=org.apache.log4j.HTMLLayout</programlisting>
        </sect3>

        <sect3>
          <title>Socket snapshot appender</title>

          <para>The <classname>SocketSnapshotAppender</classname> establishes
          a socket connection to a server and passes across the the snapshot.
          This is designed to be used with
          <classname>SnapshotServer</classname>, which collects collects
          snapshots from multiple clients.</para>

          <para>The following example sends an XML snapshot to a server on a
          private network.</para>

          <programlisting format="linespecific">log4j.appender.SocketSnapshot=org.apache.isis.core.runtime.logging.SocketSnapshotAppender
log4j.appender.SocketSnapshot.bufferSize=1024
log4j.appender.SocketSnapshot.addInfo=true
log4j.appender.SocketSnapshot.server=191.168.1.1
log4j.appender.SocketSnapshot.port=12345
log4j.appender.SocketSnapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>

          <para>The snaphot server should be directed to a maching running the
          server. The server is run using the following command:</para>

          <screen format="linespecific">java -cp isis.jar org.apache.isis.core.runtime.logging.SnapshotServer</screen>

          <para>The server needs a properties file with the following
          properties defined (with the prefix
          <methodname>isis.snapshotserver.</methodname>):-</para>

          <itemizedlist>
            <listitem>
              <para><emphasis><methodname>server</methodname></emphasis></para>

              <para>Address of the server.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>port</methodname></emphasis></para>

              <para>The port the server listens on for logging requests.
              Defaults to port 9289.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>directory</methodname></emphasis></para>

              <para>The directory path where the transferred files are to be
              saved. If none is specified then the working directory will be
              used.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>fileName</methodname></emphasis></para>

              <para>The base name of the log file, which will have timestamp
              appended. Defaults to 'log-snapshot-'.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>extension</methodname></emphasis></para>

              <para>The extension type to append to the file name.</para>
            </listitem>
          </itemizedlist>

          <para>An example configuration would be:-</para>

          <programlisting format="linespecific">isis.snapshotserver.port=12345
isis.snapshotserver.directory=logs
isis.snapshotserver.filename=log
isis.snapshotserver.extension=xml</programlisting>
        </sect3>

        <sect3>
          <title>Web snapshot appender</title>

          <para>The <classname>WebSnapshotAppender</classname> sends the
          snapshot to a web server. The following properties can be
          specified:-</para>

          <itemizedlist>
            <listitem>
              <para><emphasis><methodname>url</methodname></emphasis></para>

              <para>The <acronym>URL</acronym> of server to post data to
              (including the protocol 'http').</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>proxyAddress</methodname></emphasis></para>

              <para>Address of web proxy if one is being used.</para>
            </listitem>

            <listitem>
              <para><emphasis><methodname>proxyPort</methodname></emphasis></para>

              <para>Port of proxy server.</para>
            </listitem>
          </itemizedlist>

          <para>The following example sends a default length snapshot to the
          webserver.</para>

          <programlisting format="linespecific">log4j.appender.Remote=org.apache.isis.core.runtime.logging.WebSnapshotAppender
log4j.appender.Remote.addInfo=true
log4j.appender.Remote.locationInfo=true
log4j.appender.Remote.url=http://192.168.1.3/support/test.php
log4j.appender.Remote.layout=org.apache.log4j.HTMLLayout</programlisting>

          <para>This appender use the <acronym>HTTP</acronym> POST method to
          upload the data. It passes up a message and the snapshot as two
          parameters to the request: <varname>error</varname> and
          <varname>trace</varname>.</para>
        </sect3>
      </sect2>
    </sect1>
  </chapter>

  <chapter>
    <title><emphasis>Webapp</emphasis> Module</title>

    <abstract>
      <para>Classes and interfaces in the <package>oai.core.webapp</package>
      module.</para>
    </abstract>

    <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>

    <sect1>
      <title>Package Layering / Dependencies</title>

      <para>The packages that reside within <emphasis>core runtime</emphasis>
      break into the following layers (top layer packages depending on lower
      layers):</para>

      <screenshot>
        <screeninfo>Architecture Diagram</screeninfo>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/webapp/architecture-diagram.png"
                       scale="60" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>As the diagram show, the classes in the <emphasis>core
      runtime</emphasis> module relate either to authentication,
      authorization, image loading or the snapshot facility. Let's look at
      each in turn.</para>
    </sect1>

    <sect1>
      <title>Configuration</title>

      <para>The <classname>ConfigurationBuilderForWebApp</classname> is an
      implementation of <classname>IsisConfigurationBuilder</classname> (see
      <xref linkend="sec.ConfigurationApi" />) that is designed for use within
      webapps. It uses the associated implementation of
      <classname>ResourceStreamSource</classname> to load
      <filename>isis.properties</filename> from the
      <filename>WEB-INF</filename> directory.</para>
    </sect1>

    <sect1>
      <title>Content</title>

      <para>The servlets and filters in the
      <package>oai.isis.core.webapp.content</package> package are provided in
      order to serve up static content from either the filesystem or from the
      classpath.</para>

      <para>The <classname>ResourceServlet</classname> actually retrieves and
      serves up the content, while the
      <classname>StaticContentFilter</classname> adds response headers such as
      <code>CacheTime</code>. This can be fine-tuned through the
      <filename>web.xml</filename> file, for example:<programlisting>&lt;filter&gt;
    &lt;filter-name&gt;StaticContentFilter&lt;/filter-name&gt;
    &lt;filter-class&gt;org.apache.isis.webapp.content.StaticContentFilter&lt;/filter-class&gt;
    &lt;init-param&gt;
        &lt;param-name&gt;CacheTime&lt;/param-name&gt;
        &lt;param-value&gt;86400&lt;/param-value&gt;
    &lt;/init-param&gt;
&lt;/filter&gt;</programlisting></para>
    </sect1>

    <sect1>
      <title>Routing</title>

      <para>The <classname>RedirectToServlet</classname> (with an
      <code>init-param</code> of <emphasis>"redirectTo"</emphasis>) can be
      used to redirect a request to another request, while the
      <classname>ForwardingServlet</classname> (with an
      <code>init-param</code> of <emphasis>"forwardTo"</emphasis>) can be used
      to forward a request.</para>

      <para>For example:</para>

      <programlisting>&lt;servlet&gt;
    &lt;servlet-name&gt;RedirectToServlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.apache.isis.webapp.routing.RedirectToServlet&lt;/servlet-class&gt;
    &lt;init-param&gt;
        &lt;param-name&gt;redirectTo&lt;/param-name&gt;
        &lt;param-value&gt;/foo/bar&lt;/param-value&gt;
    &lt;/init-param&gt;
&lt;/servlet&gt;

&lt;servlet-mapping&gt;
    &lt;servlet-name&gt;RedirectToServlet&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/bar/foo&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;</programlisting>
    </sect1>
  </chapter>
</book>