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