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 2011/06/11 08:22:32 UTC
svn commit: r1134529 - in
/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide:
images/adapter-manager.png images/adapter-manager.pptx
isis-default-runtime.xml
Author: danhaywood
Date: Sat Jun 11 06:22:31 2011
New Revision: 1134529
URL: http://svn.apache.org/viewvc?rev=1134529&view=rev
Log:
updates to the runtime docbkx guide
Added:
incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.png (with props)
incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.pptx (with props)
Modified:
incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml
Added: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.png
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.png?rev=1134529&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.pptx
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.pptx?rev=1134529&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/images/adapter-manager.pptx
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml?rev=1134529&r1=1134528&r2=1134529&view=diff
==============================================================================
--- incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml (original)
+++ incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml Sat Jun 11 06:22:31 2011
@@ -61,11 +61,20 @@
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
- <para>The role of a runtime is to bootstrap the application and
- components, and to manage the lifecycle of domain object entities.
- Typically, this means managing their persistence and identity. In the case
- of the default runtime, it also means providing support for client/server
- remoting.</para>
+ <para>The role of the runtime component within <emphasis>Isis</emphasis>
+ is to bootstrap the application and components, and to manage the
+ lifecycle of domain object entities. Typically, this means managing their
+ persistence and identity.</para>
+
+ <para>The runtime component within Isis is also pluggable. This guide
+ describes the <emphasis>default runtime</emphasis> implementation, which
+ consists of a number of a parent module
+ <package>[oai.runtimes:dflt]</package> and a number of child submodules.
+ These submodules allow the behaviour of the default runtime to be
+ customized, most notably to to support different objectstores. The
+ <emphasis>default runtime</emphasis> also supports a number of other
+ capabilities, such as client/server remoting and the concept of
+ profilestores.</para>
<sect1>
<title>Who this Guide is For</title>
@@ -116,19 +125,220 @@
<part id="prt.CoreConcepts">
<title>Core Concepts</title>
+ <partintro>
+ <para></para>
+ </partintro>
+
<chapter>
<title>Core Concepts</title>
- <para></para>
+ <abstract>
+ <para>The core concepts that make up the default runtime
+ implementation.</para>
+ </abstract>
+
+ <para>The role of the runtime component within <emphasis>Isis</emphasis>
+ is to bootstrap the application and components, and to manage the
+ lifecycle of domain object entities. Typically, this means managing
+ their persistence and identity. The default runtime implementation
+ <package>[oai.runtimes:dflt]</package> provides support for this, and
+ additionally provides support for client/server remoting and also the
+ concept of a profilestore.</para>
+
+ <para>Because the scope of the <emphasis>default runtime</emphasis>
+ includes remoting, it necessarily adds a degree of abstraction that,
+ perhaps, might not otherwise be required. This chapter explains the main
+ concepts defined or implemented by the <emphasis>default
+ runtime</emphasis>.</para>
+
+ <sect1>
+ <title>Components of the Default Runtime</title>
+
+ <para>As will be clear if you've explored the codebase, the
+ <emphasis>default runtime</emphasis> implementation consists of a
+ fairly large number of submodules. These are organized around the
+ major <acronym>API</acronym>s that the default runtime exposes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>object store</para>
+
+ <para>The object store <acronym>API</acronym> defines a
+ persistence mechanism for storing domain objects. Examples include
+ a simple in-memory object store (useful only for prototyping), an
+ XML objectstore, a simple SQL objectstore, and a "NoSQL"
+ (JSON-based) objectstore.</para>
+ </listitem>
+
+ <listitem>
+ <para>bytecode providers</para>
+
+ <para>Bytecode providers provide the ability to support lazy
+ loading while walking a graph from one domain object to another.
+ This is a similar technique to that employed by
+ <acronym>ORM</acronym>s, but is available even if the object store
+ involved does not support lazy loading.<footnote>
+ <para>Indeed, ORM-based object stores (are likely to) require
+ the bytecode providers to be disabled.</para>
+ </footnote></para>
+ </listitem>
+
+ <listitem>
+ <para>profile store</para>
+
+ <para>The profile store is responsible for holding user profile
+ information, by which we mean their preferences and any other
+ information, for example bookmarks.</para>
+ </listitem>
+
+ <listitem>
+ <para>client/server remoting support</para>
+
+ <para>The default runtime also provides support for client/server
+ remoting. For example, the DnD viewer can be configured to act as
+ a client, holding a cache of domain objects client-side.
+ Interactions with these domain objects are sent transparently
+ across to a server running the same application domain classes;
+ the changes are performed server-side and the results sent back
+ down to the client where the results are merged.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title><classname>ObjectAdapter</classname>s and
+ <classname>Oid</classname>s</title>
+
+ <para><emphasis>Apache Isis</emphasis> components do not deal directly
+ with domain object pojos; instead they are always wrapped by an
+ adapter, call <classname>ObjectAdapter</classname>. This has two main
+ responsibilities:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>it provides reference to the
+ <classname>ObjectSpecification</classname>, which describes the
+ structure (properties, collections, actions) of the object's
+ type</para>
+ </listitem>
+
+ <listitem>
+ <para>it provides reference to an <classname>Oid</classname>,
+ which is an opaque value that uniquely identifies the object
+ instance.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You can think of <classname>ObjectAdapter</classname> as
+ equivalent to <classname>java.lang.Object</classname>, while
+ <classname>ObjectSpecification</classname> is in some sense equivalent
+ to <classname>java.lang.Class</classname>. The
+ <classname>Oid</classname> interface meanwhile is something akin to a
+ primary key identifier for an row in a relational database, but it is
+ slightly more abstract than that because it can also represent a
+ non-persisted object.</para>
+
+ <para>It is the <emphasis>metamodel</emphasis> module of
+ <emphasis>Isis</emphasis> <package>[oai.core:metamodel]</package>
+ defines these interfaces (<classname>ObjectAdapter,
+ ObjectSpecifation</classname> and <classname>Oid</classname>), the
+ object itself (<classname>ObjectAdapter</classname>), and the object's
+ identity (<classname>Oid</classname>). The metamodel itself also
+ provides an implementation of
+ <classname>ObjectSpecification</classname>.</para>
+
+ <para>The <emphasis>default runtime</emphasis> module
+ <package>[oai.runtimes:dflt]</package> provides an implementations of
+ the <classname>ObjectAdapter</classname> interface
+ (<classname>oai.runtimes.dflt.persistence.adapterfactory.pojo.PojoAdapter</classname>)
+ as well as an implementation of the <classname>Oid</classname>
+ interface. The actual implementation of <classname>Oid</classname>
+ will depend on the object store (persistence) mechanism that the
+ runtime has been configured to use.</para>
+ </sect1>
+
+ <sect1>
+ <title>AdapterManager</title>
+
+ <para>As already mentioned, the <classname>ObjectAdapter</classname>
+ maintains a reference to an <classname>Oid</classname> and the
+ underlying pojo domain object. To traverse in the other direction -
+ that is, from <classname>Oid</classname> to
+ <classname>ObjectAdapter</classname> or from pojo to
+ <classname>ObjectAdapter</classname> - the default runtime uses its
+ internal <classname>AdapterManager</classname> component, which
+ maintains two sets of maps. This is shown below:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/adapter-manager.png" scale="45" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The <classname>AdapterManager</classname> is an example of the
+ <ulink
+ url="http://martinfowler.com/eaaCatalog/identityMap.html">object-identity
+ map pattern</ulink> (as documented more fully in Martin Fowler's
+ Patterns of Enterprise Application Architecture). Whenever a domain
+ object pojo is handled by the system, and before an adapter for it has
+ been created, the runtime checks the
+ <classname>AdapterManager</classname> for the instance first, and only
+ creates an adapter if the pojo is not mapped. Similarly, if the
+ adapter has only an <classname>Oid</classname> value then the
+ <classname>AdapterManager</classname> is determine if the object's
+ adapter exists.</para>
+ </sect1>
+
+ <sect1>
+ <title>Lazy Loading</title>
+
+ <para></para>
+
+ <para>(eg as the result of receiving an object during a client/server
+ interaction, or from a memento, see ), then</para>
+
+ <para>This is one of the main mechanisms by which the
+ <emphasis>default runtime</emphasis> is able to support lazy loading,
+ even if the underlying object store itself does not. So, for example,
+ if an object</para>
+
+ <para></para>
+
+ <para>One of the</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Oid subtypes</title>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title></title>
+
+ <para></para>
+ </sect1>
<sect1>
<title>IsisContext</title>
<para><emphasis>Context</emphasis></para>
- <para>The ObjectAdapterContext provide access to the main components
- of the NOF. If the system is started in a multi-user mode then the
- context will hold specific components for specific execution contexts,
+ <para>The <classname>IsisContext</classname> class responsibility
+ provide access to the main components of the framework.</para>
+
+ <para>If the system is started in a multi-user mode then the context
+ will hold specific components for specific execution contexts,
allowing the same process to access the same components and different
processes to access unique instances.</para>
@@ -150,19 +360,6 @@
<para></para>
- <para><emphasis>Identity map</emphasis></para>
-
- <para>Any object that has identity (whether it is persisted or not)
- must be registered with the identity map. This maps two relationships:
- domain objects to proxies and OIDs to proxies.</para>
-
- <para>Whenever a domain object is handled by the system, and before a
- proxy is created, it must be checked against the identity map and if
- it exists the proxy already in the identity map must be used instead
- of creating a new proxy.</para>
-
- <para></para>
-
<para></para>
</sect1>
@@ -184,7 +381,7 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/architecture.gif" scale="30" />
+ <imagedata fileref="images/architecture.gif" scale="40" />
</imageobject>
</mediaobject>
@@ -221,21 +418,6 @@
</sect1>
<sect1>
- <title>IdentityMap</title>
-
- <para></para>
-
- <para>A persistor should utilise an object-identity map (see Martin
- Fowler's Patterns of Enterprise Application Architecture) to manage
- the mapping of domain objects and adapters, and OIDs and adapters. For
- each domain object the map should store a single adapter, and an OID
- to that same adapter. The persitor can then guarantee that the same
- adapter is always provided for a specific domain object or OID</para>
-
- <para></para>
- </sect1>
-
- <sect1>
<title>Profile Stores</title>
<para></para>