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 2012/12/06 18:42:17 UTC
[25/52] [partial] ISIS-188: moving framework/ subdirs up to parent
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml b/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
new file mode 100644
index 0000000..86b634a
--- /dev/null
+++ b/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
@@ -0,0 +1,1293 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"file:./src/docbkx/dtd-4.5/docbookx.dtd">
+<book>
+ <bookinfo>
+ <title><?eval ${docbkxGuideTitle}?></title>
+
+ <subtitle><?eval ${docbkxGuideSubTitle}?></subtitle>
+
+ <releaseinfo><?eval ${project.version}?></releaseinfo>
+
+ <authorgroup>
+ <author>
+ <firstname>Dan</firstname>
+
+ <surname>Haywood</surname>
+ </author>
+ </authorgroup>
+
+ <legalnotice>
+ <para>Permission is granted to make and distribute verbatim copies of
+ this manual provided that the copyright notice and this permission
+ notice are preserved on all copies.</para>
+ </legalnotice>
+ </bookinfo>
+
+ <toc></toc>
+
+ <preface id="preface">
+ <title>Preface</title>
+
+ <para><emphasis>Apache Isis</emphasis> is designed to allow programmers
+ rapidly develop domain-driven applications following the <ulink
+ url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
+ pattern. It is made up of a core framework that supports supports various
+ viewers, along with <acronym>API</acronym>s and implementations relating
+ to security, the programming model, the runtime (persistence) and profile
+ stores (user preferences). <emphasis>Apache Isis</emphasis> is hosted at
+ the <ulink url="http://incubator.apache.org/isis">Apache
+ Foundation</ulink>, and is licensed under <ulink
+ url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
+ License v2</ulink>.</para>
+
+ <para>At the heart of <emphasis>Apache Isis</emphasis> is a metamodel,
+ used by the viewers to render the domain objects and by the runtime to
+ persist them, remote them, and so forth. This metamodel is built up by the
+ framework looking for specific programming conventions, annotations and so
+ forth. The collection of programming conventions is termed a "programming
+ model", and is pluggable.</para>
+
+ <para>This guide describes how to use and customize the default
+ programming models, or to use other available programming models (for
+ example, for other JVM-based languages).</para>
+
+ <sect1>
+ <title>Who this Guide is For</title>
+
+ <para>This guide is written for programmers looking to either customize
+ the default programming model (adding or removing programming
+ conventions), or to use other available programming models. It is
+ divided into the following parts:<itemizedlist>
+ <listitem>
+ <para>Default Programming Model</para>
+
+ <para>This part of the guide (see <xref linkend="prt.Java5" />)
+ covers the default (Java 5) programming model, how to customize
+ it, and how to extend it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Groovy Programming Model</para>
+
+ <para>This part of the guide (see <xref linkend="prt.Groovy" />)
+ describes how to configure your application to use Groovy as the
+ programming language for your domain objects, rather than
+ Java.</para>
+ </listitem>
+
+ <listitem>
+ <para>Wrapper Programming Model</para>
+
+ <para>The wrapper programming model enables a domain object to be
+ "wrapped" by a proxy so that interactions with it by other domain
+ objects are "as if" through the viewer. This part of the guide
+ (see <xref linkend="prt.Wrapper" />) describes how to configure
+ your application in order that your domain objects can take
+ advantage of this capabilities.</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>How this Guide relates to other Documentation</title>
+
+ <para>If all you want to do is to program domain objects against the
+ default programming model, then see the Isis <emphasis>applib</emphasis>
+ documentation.</para>
+
+ <para>If you want to start customizing the default programming model,
+ however, then we recommend that you first consult Isis'
+ <emphasis>core</emphasis> documentation, which, describes the general
+ design of the metamodel (in the <emphasis>core metamodel</emphasis>
+ chapter), and then get an understanding of the library of programming
+ model elements available to assemble a programming model (in the
+ <emphasis>core progmodel</emphasis> chapter). You can then turn to
+ <emphasis>this</emphasis> guide which describes which of those elements
+ are actually used for the default programming model (most of
+ them).</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 <emphasis>default
+ runtime</emphasis> module. In this guide we also use the "oai"
+ abbreviation within package names.</para>
+ </sect1>
+ </preface>
+
+ <part id="prt.Java5">
+ <title>Default (Java 5) Programming Model</title>
+
+ <partintro>
+ <para><emphasis>Apache Isis</emphasis>' default programming model
+ <package>[oai.progmodels:dflt]</package> is targetted at domain
+ applications written using Java 5, and corresponds to the set of
+ programming conventions described in the documentation fo the
+ <emphasis>applib</emphasis> <package>[oai:applib]</package> module. If
+ using the <emphasis>default runtime</emphasis>
+ <package>[oai.runtimes:dflt]</package> then the Java 5 programming model
+ is configured by default .</para>
+
+ <para>The chapters in this part of the guide describe:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>using and customizing the default programming model</para>
+ </listitem>
+
+ <listitem>
+ <para>writing a new <classname>FacetFactory</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>writing a new <classname>FacetDecorator</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>writing a new <classname>MetaModelValidator</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>writing a new
+ <classname>MemberLayoutArranger</classname></para>
+ </listitem>
+ </itemizedlist>
+ </partintro>
+
+ <chapter id="chp.ProgrammingModelApi">
+ <title>Using the Default Programming Model</title>
+
+ <para>We generally recommend that you stick to the conventions of the
+ programming model as documented in the <emphasis>applib</emphasis>
+ module <package>[oai:applib]</package>. However, it is in fact possible
+ to customize or modify these conventions. A typical case might be to
+ make <emphasis>Isis</emphasis> support some of your own annotations.
+ You'll find that some of the viewers and object stores also define their
+ own extensions to the standard programming model.</para>
+
+ <para>In this chapter we show you how to use the default programming
+ model, and then we go on to show how to customise it to your own
+ needs.</para>
+
+ <sect1>
+ <title>*** The Default Programming Model
+ (<classname>ProgrammingModelFacetsJava5</classname>)</title>
+
+ <para>*** show what is used by default; how to specify explicitly in
+ <emphasis>default runtime</emphasis> if required.</para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>*** Minor Customizations to the Programming Model</title>
+
+ <para>*** discuss use of .include and .exclude</para>
+
+ <programlisting>isis.reflector.facets.include=com.mycompany.myproj.isis.StringLengthBetweenFacetFactory,\ com.mycompany.myproj.isis.PositiveValuesOnlyFacetFactory</programlisting>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>*** Writing a Custom
+ <classname>ProgrammingModel</classname></title>
+
+ <para>*** recommended approach is to subclass
+ <classname>ProgrammingModelFacetsJava5</classname>:</para>
+
+ <para></para>
+
+ <para></para>
+
+ <programlisting format="linespecific">isis.reflector.facets=com.mycompany.myproj.isis.MyProgrammingModel</programlisting>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Writing a New <classname>FacetFactory</classname></title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>*** NameFileFacetFactory</title>
+
+ <para>*** copied from trunk/examples</para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>*** TitleAnnotationFacetFactory</title>
+
+ <para>*** write a-new; render the title using those properties
+ annotated as @Title(n) (where n=order)</para>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>*** StringLengthBetweenFacetFactory</title>
+
+ <para>*** write a-new</para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Writing a New <classname>FacetDecorator</classname></title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>*** LoggingFacetDecorator</title>
+
+ <para></para>
+
+ <para>*** eg for capture of response times, or for replay</para>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Writing a New <classname>MetaModelValidator</classname></title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>*** Require all pojos are annotated</title>
+
+ <para></para>
+
+ <para>eg @Root vs @Entity vs @Value vs @Service</para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Writing a New <classname>MemberLayoutArranger</classname></title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>*** FileBasedMemberLayoutArranger</title>
+
+ <para></para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+ </part>
+
+ <part id="prt.Groovy">
+ <title>Groovy Programming Model</title>
+
+ <partintro>
+ <para><emphasis>Apache Isis</emphasis> enables design-driven
+ applications to be rapidly developed and optionally deployed,
+ automatically providing a runtime-generated <acronym>OOUI</acronym> for
+ the domain objects. <emphasis>Isis</emphasis> itself is written in Java,
+ and normally the domain objects that make up the application are also
+ written in Java. These objects are basically pojos;
+ <emphasis>Isis</emphasis> provides a number of annotations and defines a
+ number of coding conventions so that business rules and constraints can
+ be picked up by the framework, and to expose behaviour in the
+ <acronym>UI</acronym> over-and-above simple <acronym>CRUD</acronym>
+ operations.</para>
+
+ <para><ulink url="http://groovy.codehaus.org">Groovy</ulink> is an
+ alternative language for writing code to run on the
+ <acronym>JVM</acronym>. It offers a number of dynamic language features,
+ as well reduced syntax clutter (eg for properties) along with
+ programming constructs such as closures. What the Groovy programming
+ model <package>[oai.progmodels:groovy]</package>does is to provide is
+ the ability to write domain objects in Groovy and then run on top within
+ <emphasis>Apache Isis</emphasis>. Because Groovy source files are
+ ultimately compiled down into Java bytecode, <emphasis>Isis</emphasis>
+ is able (with a little bit of tweaking) to build up its metamodel and
+ run as normal. What the <emphasis>groovy progmodel</emphasis> does is
+ perform the tweaking in how the metamodel is built up.</para>
+
+ <para>The chapters in this part of the guide:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>how to configure Maven for an existing domain application to
+ use the Groovy</para>
+
+ <para>We generally recommend you develop your domain applications
+ using <ulink url="http://maven.apache.org">Apache Maven</ulink>, and
+ <emphasis>Isis</emphasis>itself is packaged as a set of Maven
+ modules. The details provided focus solely on how to update a
+ Maven-based project; we also explain how to configure your
+ application within an <acronym>IDE</acronym>.</para>
+ </listitem>
+
+ <listitem>
+ <para>writing domain objects in Groovy</para>
+
+ <para>Guidance on how to follow the <emphasis>Apache Isis</emphasis>
+ coding conventions while programming in Groovy.</para>
+ </listitem>
+
+ <listitem>
+ <para>writing fixtures in Groovy</para>
+
+ <para>For testing and prototyping.</para>
+ </listitem>
+ </itemizedlist>
+ </partintro>
+
+ <chapter>
+ <title>Configuring your Domain Application's (Maven) Project</title>
+
+ <abstract>
+ <para>In this chapter we explain the configurations steps necessary to
+ update your Maven-based domain application, and how to configure a
+ common <acronym>IDE</acronym> so you can program in Groovy with
+ <emphasis>Apache Isis</emphasis>.</para>
+ </abstract>
+
+ <sect1>
+ <title>Review: structure of an Isis Application</title>
+
+ <para>The typical structure for a <emphasis>Apache Isis
+ </emphasis>Maven-based application (and the one you'll end up with if
+ you use <emphasis>Apache Isis</emphasis>' quickstart archetype)
+ is:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>app</filename></para>
+
+ <para>Root (parent) module, whose <filename>pom.xml</filename>
+ references the submodules</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/dom</filename></para>
+
+ <para>Domain object model, plus interfaces for services,
+ repositories and factories</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/fixture</filename></para>
+
+ <para>Fixtures, used to seed the default object store when running
+ in exploration/prototype mode</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/objstore-dflt</filename></para>
+
+ <para>Implementation of services, repositories and factories for
+ use with the default runtime/default (in-memory) object
+ store.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/quickrun</filename></para>
+
+ <para>Bootstrap for running from the command line (the
+ <acronym>DnD</acronym> viewer, the <acronym>HTML</acronym> viewer,
+ the <acronym>JSON</acronym> viewer or the <acronym>XHTML</acronym>
+ viewer)</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/viewer-xxx</filename></para>
+
+ <para>Packaging and running as a web application using the 'xxx'
+ viewer (where xxx=html, restful, scimpi or wicket)</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>app/test-xxx</filename></para>
+
+ <para>Running as tests (where xxx=junit or bdd)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The application is normally run either from the
+ <emphasis>quickrun</emphasis> project, using the
+ <code>org.apache.isis.Isis</code> main class, and where the viewer to
+ use is specified using the <classname>--viewer</classname> flag).
+ Alternatively it can be run as a webapp from the
+ <emphasis>viewer-xxx</emphasis> projects.</para>
+ </sect1>
+
+ <sect1>
+ <title>Updating the Parent Project</title>
+
+ <para>There is no Groovy code in the root parent project, but what we
+ do here is to define the version, and where necessary configuration,
+ of dependencies used by the application's submodules. We have
+ classpath dependencies and build dependencies, so both are
+ defined.</para>
+
+ <para>There are three things to specify:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>which version of the Groovy runtime to use</para>
+ </listitem>
+
+ <listitem>
+ <para>which version of GMaven to use. GMaven is the Groovy maven
+ plugin that we use to compile Groovy, hosted at <ulink
+ url="http://docs.codehaus.org/display/GMAVEN/Home">codehaus.org</ulink>.
+ By default GMaven specifies a version of the Groovy runtime to
+ compile against, but this can be overridden</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To start with, we specify the versions of these different
+ components, by adding the following to the
+ <filename>pom.xml</filename>:</para>
+
+ <programlisting><properties>
+ <groovy.version>1.7.2</groovy.version>
+ <gmaven.version>1.2</gmaven.version>
+ <gmaven.runtime>1.7</gmaven.runtime>
+</properties></programlisting>
+
+ <para>The <varname>gmaven.runtime</varname> must be compatible with
+ the <varname>groovy.version</varname>. Typically, if the
+ <varname>groovy.version</varname> is <literal>x.y.z</literal>, then
+ the <varname>gmaven.runtime</varname> will be simply
+ <literal>x.y</literal>. The documentation on <ulink
+ url="http://docs.codehaus.org/display/GMAVEN/Groovy+Runtime">GMaven
+ providers</ulink> for further details; running <code>mvn
+ groovy:providers</code> is a good place to start.</para>
+
+ <blockquote>
+ <para>Note: the <emphasis>groovy progmodel </emphasis>also has a
+ dependency on the Groovy runtime, albeit in a very minor way. This
+ dependency is marked optional in order to allow your application to
+ specify its own Groovy runtime version which if needed can be
+ different from that needed by <emphasis>groovy progmodel</emphasis>
+ module.</para>
+ </blockquote>
+
+ <para>Then, we define how we to compile Groovy code, using the GMaven
+ plugin. We specify the plugin, the version, and its configuration;
+ this goes in
+ <classname><build>/<pluginManagement></classname>:</para>
+
+ <programlisting><build>
+ <pluginManagement>
+ <plugins>
+ ...
+
+ <plugin>
+ <groupId>org.codehaus.gmaven</groupId>
+ <artifactId>gmaven-plugin</artifactId>
+ <version>${gmaven.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>compile</goal>
+ <goal>testCompile</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <providerSelection>${gmaven.runtime}</providerSelection>
+ </configuration>
+ </plugin>
+
+ </plugins>
+ </pluginManagement>
+</build></programlisting>
+
+ <para>Finally, we define the dependencies to Groovy. This goes in
+ <classname><dependencyManagement>/<dependencies></classname>:</para>
+
+ <programlisting><dependencyManagement>
+ <dependencies>
+ ...
+ <dependency>
+ <groupId>org.codehaus.groovy</groupId>
+ <artifactId>groovy-all</artifactId>
+ <version>${groovy.version}</version>
+ </dependency>
+ ...
+ </dependencies>
+</dependencyManagement></programlisting>
+
+ <para>The dependency to <emphasis>groovy progmodel</emphasis> modules
+ themselves can be set up through a scope=import dependency of
+ [org.apache.isis:release]. Note that the quickstart archetype does
+ this automatically:</para>
+
+ <programlisting><dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.isis</groupId>
+ <artifactId>release</artifactId>
+ <version>${isis.version}</version>
+ </dependency>
+ ...
+</dependencies></programlisting>
+
+ <para>where <code>${isis.version}</code> is the version of
+ <emphasis>Apache Isis</emphasis> being used.</para>
+ </sect1>
+
+ <sect1>
+ <title>Updating the DOM Project</title>
+
+ <para>The <emphasis>dom</emphasis> project is the place where the bulk
+ of your domain objects live. Since these are now written in Groovy, we
+ need to ensure that they are compiled.</para>
+
+ <sect2>
+ <title>Source folders</title>
+
+ <para>First off, we must separate our Groovy code from any Java
+ code. To do this, create the following folders:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>src/main/groovy</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>src/test/groovy</filename></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>It's important to create both of these folders (even if you
+ aren't planning on writing any unit tests ;-) ... the
+ <acronym>IDE</acronym> integration that we describe below insists
+ upon it.</para>
+ </sect2>
+
+ <sect2>
+ <title>Updating the Maven POMs</title>
+
+ <para>First, we update the <acronym>POM</acronym> our domain objects
+ are compiled using the Groovy compiler. Add the following into
+ <classname><build></classname>:</para>
+
+ <programlisting><build>
+ <plugins>
+
+ <plugin>
+ <groupId>org.codehaus.gmaven</groupId>
+ <artifactId>gmaven-plugin</artifactId>
+ </plugin>
+
+ </plugins>
+</build></programlisting>
+
+ <para>Next, we add dependencies both to <emphasis>groovy
+ progmodel</emphasis>'s own applib
+ <package>[oai.progmodels:groovy-applib]</package> and to Groovy
+ itself:</para>
+
+ <programlisting><dependencies>
+ ...
+
+ <dependency>
+ <groupId>org.apache.isis.progmodels</groupId>
+ <artifactId>groovy-applib</artifactId>
+ </dependency>
+
+ <dependency>
+ <groupId>org.codehaus.groovy</groupId>
+ <artifactId>groovy-all</artifactId>
+ </dependency>
+
+</dependencies></programlisting>
+
+ <para>The <emphasis>groovy progmodel</emphasis> applib brings in a
+ transitive dependency to <emphasis>Isis </emphasis>main applib along
+ one or two helper classes (of which more in <xref
+ linkend="chp.Fixtures" />).</para>
+
+ <note>
+ <para>In the future the applib may be expanded to include other
+ helper classes or new annotations provided by <emphasis>Groovy
+ Objects</emphasis> itself.</para>
+ </note>
+
+ <para>Finally, a small workaround. <emphasis>Apache Isis
+ </emphasis>picks up icons for domain classes from the classpath,
+ with the Java compiler doing the job of copying these icons from
+ <filename>src/main/resources</filename> into target. The Groovy
+ compiler does not seem to do this. We therefore ensure that the Java
+ compiler runs by adding a small dummy Java class. It could go
+ anywhere, but the <classname>images</classname> package is probably
+ the best location:</para>
+
+ <programlisting>package images;
+
+/**
+ * workaround to force Java compiler to kick in and copy images over to target classpath
+ */
+class Dummy {}</programlisting>
+
+ <para>At this point you should be able to build your project from
+ the Maven command line. Let's see how to add in
+ <acronym>IDE</acronym> support.</para>
+ </sect2>
+
+ <sect2>
+ <title>Configuring Eclipse IDE</title>
+
+ <para>If you are using Eclipse <acronym>IDE</acronym>, then you can
+ add in Groovy support using the <ulink
+ url="http://groovy.codehaus.org/Eclipse+Plugin">GroovyEclipse</ulink>
+ plugin.</para>
+
+ <para>To start off with, install the plugin into your
+ <acronym>IDE</acronym> using the standard Eclipse update mechanisms.
+ There's a detailed <ulink
+ url="http://docs.codehaus.org/display/GROOVY/Install+Groovy-Eclipse+Plugin">walkthrough</ulink>
+ on the Groovy wiki if you need it.</para>
+
+ <para>Next, enable the Groovy nature in your
+ <emphasis>dom</emphasis> project:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/ConvertToGroovy.png" scale="40" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Doing this brings in Groovy editor and compiler support
+ (technically: the Groovy nature is added to the project). But it
+ also adds in a reference to the Groovy runtime to our classpath,
+ which we don't need because we already have courtesy of Maven.
+ Therefore, remove the <emphasis>Groovy Libraries</emphasis>
+ classpath library:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/RemoveGroovyLibraryFromClasspath.png"
+ scale="40" />
+ </imageobject>
+ </mediaobject>
+
+ <para>And that should do the trick.</para>
+ </sect2>
+
+ <sect2>
+ <title>Other IDEs</title>
+
+ <para>If you use another <acronym>IDE</acronym>, please let us know
+ what the steps are to configure it, and we'll update this
+ documentation.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Updating the Fixture and Service Projects</title>
+
+ <para>As well as using Groovy for the <emphasis>dom</emphasis>
+ project, you may well want to use it for the
+ <emphasis>fixture</emphasis> project and the
+ <emphasis>service</emphasis> implementations project. In which case,
+ just follow the same steps as the described for the
+ <emphasis>dom</emphasis> project.</para>
+ </sect1>
+
+ <sect1>
+ <title>Updating the <filename>quickrun</filename> and/or
+ <filename>viewer-xxx</filename> projects</title>
+
+ <para>Finally, we need to update the <emphasis>quickrun</emphasis>
+ and/or <emphasis>viewer-xxx</emphasis> project (depending on how you
+ intend to bootstrap your application). First, we add a dependency to
+ <emphasis>groovy progmodel</emphasis>s'<filename> </filename>metamodel
+ module <package>[oai.progmodels:groovy-metamodel]</package>, in
+ <classname><dependencies></classname>:</para>
+
+ <programlisting><dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.isis.progmodels</groupId>
+ <artifactId>groovy-metamodel</artifactId>
+ </dependency>
+ ...
+</dependencies></programlisting>
+
+ <para>Then, update the <filename>isis.properties</filename> config
+ file as follows:</para>
+
+ <programlisting>isis.reflector.facets.include=org.starobjects.groovy.gmetamodel.RemoveGroovyMethodsFacetFactory</programlisting>
+
+ <para>This little piece of magic ensures that the various methods that
+ the Groovy compiler adds behind the scenes are filtered out so that
+ they don't appear in the <emphasis>Isis</emphasis> metamodel.</para>
+
+ <para>In most circumstances that should be enough. If you have very
+ deep hierarchies of domain classes, then you may also need to add
+ in:</para>
+
+ <programlisting>isis.groovy.depth=NNN</programlisting>
+
+ <para>where NNN should be the depth of the class hierarchy. The
+ default is 5, so in many cases there won't be any need to add this
+ key. (The reason this is needed is that the Groovy compiler seems to
+ generate a set of methods for each level of the class
+ hierarchy).</para>
+
+ <para>And you should be good to go.</para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Writing Domains Object in Groovy</title>
+
+ <abstract>
+ <para><emphasis>Apache Isis </emphasis> uses convention over
+ configuration and annotations to build the metamodel of the domain
+ objects. This chapter explains what those conventions look like, and
+ where annotations should be applied, when developing domain objects in
+ Groovy.</para>
+ </abstract>
+
+ <para><emphasis>Apache Isis </emphasis>allows validation and other
+ business constraints to expressed either declaratively (using
+ annotations) and/or imperatively (using supporting methods). For a given
+ class member (property, collection or action) we can specify whether the
+ member:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>is visible, and if so, is it</para>
+ </listitem>
+
+ <listitem>
+ <para>is usable, and if modified, whether the proposed change</para>
+ </listitem>
+
+ <listitem>
+ <para>is valid</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Or, slightly more pithily, <emphasis>can you see it, can you use
+ it, can you do it</emphasis>.</para>
+
+ <para>Any public methods that don't represent properties or collections
+ are interpreted as being actions. These are surfaced in the
+ <acronym>UI</acronym> (as menu items or buttons) to provide arbitrary
+ business behaviour (this is what makes <emphasis>Naked
+ Objects</emphasis> applications more than a simple
+ <acronym>CRUD</acronym> framework).</para>
+
+ <para>There are also a number of reserved method names that are used
+ either as rendering hints or to define lifecycle callbacks.</para>
+
+ <para>Collectively these conventions and annotations define the
+ <emphasis>Isis Programming Model</emphasis>. This chapter should give
+ you a good flavour of what it's like to writing applications for this
+ programming model; but refer to the <emphasis>applib
+ </emphasis>documentation for the complete reference.</para>
+
+ <sect1>
+ <title>(Optional) Superclass</title>
+
+ <para>Typically domain objects subclass from
+ <classname>AbstractDomainObject</classname> (in the
+ <emphasis>Isis</emphasis> applib, transitively referenced from
+ <emphasis>Groovy Objects</emphasis>' own applib); for example:</para>
+
+ <programlisting>class Claim extends AbstractDomainObject {
+ ...
+}</programlisting>
+
+ <para>It isn't mandatory to subclass from
+ <classname>AbstractDomainObject</classname>. All that <emphasis>Isis
+ </emphasis>requires is that it can inject its
+ <classname>DomainObjectContainer</classname> into the domain object to
+ support lazy loading and dirty tracking. The
+ <classname>DomainObjectContainer</classname> also allows your domain
+ object to be able to instantiate and persist new instances (using the
+ <methodname>newTransientInstance()</methodname> and
+ <methodname>persist()</methodname> methods).</para>
+
+ <para>In practical terms, then, if you aren't able or don't want to
+ subclass from <classname>AbstractDomainObject</classname>, just make
+ sure you push down the above methods into your own objects (probably
+ by way of a project-specific superclass).</para>
+ </sect1>
+
+ <sect1>
+ <title>Properties and Collections</title>
+
+ <para><emphasis>Isis </emphasis>follows the usual JavaBean conventions
+ for properties, and so any Groovy property is picked up automatically
+ by the framework. This also works for collections (a JavaBean property
+ that returns a <classname>java.util.Collection</classname>,
+ <classname>java.util.List</classname> or
+ <classname>java.util.Set</classname>).</para>
+
+ <para>For example, the <classname>Claim</classname> object is rendered
+ like this:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/title.png" scale="60" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The corresponding Groovy source code is:</para>
+
+ <programlisting>class Claim extends AbstractDomainObject {
+
+ boolean rush
+ String description
+ Date date
+ String status
+ Claimant claimant
+ Approver approver
+ List<ClaimItem> items = new ArrayList<ClaimItem>()
+
+ ...
+}</programlisting>
+ </sect1>
+
+ <sect1>
+ <title>Title & Icon</title>
+
+ <para><emphasis>Apache Isis</emphasis> uses the
+ <methodname>title()</methodname> method to render a label for domain
+ objects. For the <classname>Claim</classname> class, this is defined
+ as:</para>
+
+ <programlisting>class Claim extends AbstractDomainObject {
+
+ ...
+
+ String title() { status + " - " + date }
+
+ ...
+}</programlisting>
+
+ <para>It's important that this is defined as returning a
+ <emphasis>java.lang.String</emphasis>; a simple Groovy
+ <token>def</token> is not sufficient.</para>
+
+ <para>In addition, you may want to define an
+ <methodname>iconName()</methodname>. If present, this is used to
+ locate the icon for the entity (meaning that different instances of
+ the same type can render different icons). Otherwise, <emphasis>Isis
+ </emphasis>infers the icon from the class name. The icon is typically
+ picked up from an <package>images</package> package (in
+ <filename>src/main/resources</filename>).</para>
+ </sect1>
+
+ <sect1>
+ <title>Creating and Persisting Objects</title>
+
+ <para><emphasis>Isis</emphasis> will automatically inject any domain
+ services into your domain objects, but to do this must know about then
+ when they are instantiated. But it also requires to know about them so
+ that it can track their persistence state. To do this, use the
+ <methodname>DomainObjectContainer#newTransientInstance(Class)</methodname>
+ method. Note that this also requires that your domain object has a
+ <code>public</code> no-arg constructor.</para>
+
+ <para>Similarly, if you want to persist a domain object, use
+ <methodname>DomainObjectContainer#persist()</methodname>.</para>
+
+ <para>If inheriting from <classname>AbstractDomainObject</classname>,
+ then there are helper methods that delegate to the container for
+ you.</para>
+ </sect1>
+
+ <sect1>
+ <title>Callbacks</title>
+
+ <para>There are a number of callback methods that
+ <emphasis>Isis</emphasis> will call on your domain object if present.
+ One of these is <methodname>created()</methodname>, called after a
+ transient instance is just instantiated. It's a good place to perform
+ initialization logic (that would otherwise probably have lived in a
+ constructor). For example:</para>
+
+ <programlisting>class Claim extends AbstractDomainObject {
+
+ ...
+
+ void created() {
+ status = "New"
+ date = new Date()
+ }
+
+ ...
+}</programlisting>
+
+ <para>Note that the method must return <code>void</code> (Groovy's
+ <code>def</code> returns a <classname>java.lang.Object</classname>,
+ which is not what <emphasis>Isis</emphasis> is looking for).</para>
+
+ <para>Other callback methods include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><methodname>loading()</methodname> and
+ <methodname>loaded()</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>persisting()</methodname> and
+ <methodname>persisted()</methodname> (or
+ <methodname>saving()</methodname> and
+ <methodname>saved()</methodname> if you prefer)</para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>updating()</methodname> and
+ <methodname>updated()</methodname></para>
+ </listitem>
+
+ <listitem>
+ <para><methodname>removing()</methodname> and
+ <methodname>removed()</methodname> (or
+ <methodname>deleting()</methodname> and
+ <methodname>deleted()</methodname> if you prefer)</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Annotations</title>
+
+ <para>Declarative business rules amount to applying annotations on the
+ appropriate methods. However, <emphasis>Isis</emphasis> does not
+ (currently) support annotations on fields, so it's necessary to put
+ the annotation on the getter for the property.</para>
+
+ <para>For example, to indicate that a property is disabled
+ (read-only), we can write:</para>
+
+ <programlisting>class Claim ... {
+ String status
+ ...
+
+ @Disabled
+ String getStatus() { status }
+}</programlisting>
+
+ <para>Other annotations are used as hints for the user interface. For
+ example the <classname>@MemberOrder</classname> is used to specify the
+ order in which properties and collections appear in the
+ <acronym>UI</acronym>:</para>
+
+ <programlisting>class Claim ... {
+ String status
+ ...
+
+ @MemberOrder("3")
+ String getStatus() { status }
+}</programlisting>
+
+ <para>Another annotation is <classname>@Named</classname>, which
+ commonly appears on action parameters if using built-in value types.
+ For example, the <classname>Claim</classname>'s
+ <methodname>addItem()</methodname> action looks like:</para>
+
+ <programlisting>class Claim ... {
+
+ void addItem(
+ @Named("Days since") int days,
+ @Named("Amount") double amount,
+ @Named("Description") String description) {
+ ClaimItem claimItem = newTransientInstance(ClaimItem.class)
+ Date date = new Date()
+ date = date.add(0, 0, days)
+ claimItem.dateIncurred = date
+ claimItem.description = description
+ claimItem.amount = new Money(amount, "USD")
+ persist(claimItem)
+ addToItems(claimItem)
+ }
+ ...
+}</programlisting>
+
+ <para>The full list of annotations are documented in the
+ <emphasis>applib</emphasis> <package>[oai:applib]</package>
+ documentation.</para>
+ </sect1>
+
+ <sect1>
+ <title>Supporting Methods</title>
+
+ <para>Business rules can also be specified imperatively, using
+ supporting methods. These methods are associated back to the class
+ member (property, collection or action) using a simple prefix. For
+ example, to imperatively disable the
+ <methodname>addItem()</methodname> action for a
+ <classname>Claim</classname>, we could use:</para>
+
+ <programlisting>class Claim ... {
+
+ void addItem(
+ @Named("Days since") int days,
+ @Named("Amount") double amount,
+ @Named("Description") String description) {
+ ...
+ }
+ String disableAddItem() {
+ status == "Submitted" ? "Already submitted" : null
+ }
+ ...
+}</programlisting>
+
+ <para>Returning a non-null value means the action (or more generally
+ class member) should be disabled; the string returned is the reason
+ why the action cannot be invoked.</para>
+
+ <para>There are supporting methods for each of the three levels of
+ business rules ("see it, use it, do it"), with the prefix being
+ <methodname>hideXxx()</methodname>,
+ <methodname>disableXxx()</methodname> and
+ <methodname>validateXxx()</methodname>. The
+ <methodname>hideXxx()</methodname> returns a <code>boolean</code>, the
+ other two (as you've just seen) return a
+ <classname>String</classname>. In the case of
+ <methodname>validateXxx()</methodname>, the method takes arguments to
+ allow validation to be performed, for example:</para>
+
+ <programlisting>class Claim ... {
+
+ ...
+ String validateAddItem(int days, double amount, String description) {
+ if (days <= 0) "Days must be positive value"
+ }
+ ...
+}</programlisting>
+
+ <para>There are a couple of other supporting methods that can be
+ provided. The <methodname>defaultXxx()</methodname> prefix is used to
+ provide a default either for a property of a newly instantiated
+ object, or, more commonly, as the default for a parameter of an
+ action. In the latter case the argument number is specified:</para>
+
+ <programlisting>class Claim ... {
+
+ ...
+ int default0AddItem() { 1 }
+ ...
+}</programlisting>
+
+ <para>In a similar vein, the <methodname>choicesXxx()</methodname>
+ prefix provides a list of choices for a property or for an action
+ parameter:</para>
+
+ <programlisting>class Claim ... {
+
+ ...
+ List<String> choices2AddItem() { ["meal", "taxi", "plane", "train"] }
+ ...
+}</programlisting>
+
+ <para>There's no requirement for <methodname>choicesXxx()</methodname>
+ to tie in with <methodname>validateXxx()</methodname> or
+ <methodname>defaultXxx()</methodname>, but they usually are consistent
+ with each other.</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.Fixtures">
+ <title>Writing Fixtures in Groovy</title>
+
+ <abstract>
+ <para>We can take advantage of one of Groovy's features to reduce the
+ boilerplate when writing fixtures. This chapter explains how.</para>
+ </abstract>
+
+ <para>One of the classes provided by the Groovy runtime is
+ <classname>ObjectGraphBuilder</classname>, which (as per its <ulink
+ url="http://groovy.codehaus.org/ObjectGraphBuilder">documentation</ulink>)
+ is "a builder for an arbitrary graph of beans that follow the JavaBean
+ convention,... useful for creating test data for example". Which is,
+ indeed, exactly what we need to do when we create fixtures for use with
+ the in-memory object store.</para>
+
+ <para>The <emphasis>groovy progmodel </emphasis>applib extends this
+ class by providing the <classname>DomainObjectBuilder</classname>, which
+ additionally ensures that domain objects are instantiated through the
+ <classname>DomainObjectContainer</classname>. The original
+ <classname>ObjectGraphBuilder</classname> also needs to be told
+ explicitly where the domain object packages are, so
+ <classname>DomainObjectBuilder</classname> makes this easy to do in a
+ typesafe way.</para>
+
+ <para>Let's see it in action. Here's a fixture to create 3
+ <classname>Employee</classname>s, some <classname>Claim</classname>s and
+ some <classname>ClaimItem</classname>s within those
+ <classname>Claim</classname>s:</para>
+
+ <programlisting>class ClaimsFixture extends AbstractFixture {
+
+ @Override
+ public void install() {
+ def builder = new DomainObjectBuilder(getContainer(), Employee.class, Claim.class)
+
+ builder.employee(id: 'fred', name:"Fred Smith")
+ builder.employee(id: "tom", name: "Tom Brown") {
+ approver( refId: 'fred')
+ }
+ builder.employee(name: "Sam Jones") {
+ approver( refId: 'fred')
+ }
+
+ builder.claim(id: 'tom:1', date: days(-16), description: "Meeting with client") {
+ claimant( refId: 'tom')
+ claimItem( dateIncurred: days(-16), amount: money(38.50), description: "Lunch with client")
+ claimItem( dateIncurred: days(-16), amount: money(16.50), description: "Euston - Mayfair (return)")
+ }
+ builder.claim(id: 'tom:2', date: days(-18), description: "Meeting in city office") {
+ claimant( refId: 'tom')
+ claimItem( dateIncurred: days(-18), amount: money(18.00), description: "Car parking")
+ claimItem( dateIncurred: days(-18), amount: money(26.50), description: "Reading - London (return)")
+ }
+ builder.claim(id: 'fred:1', date: days(-14), description: "Meeting at clients") {
+ claimant( refId: 'fred')
+ claimItem( dateIncurred: days(-14), amount: money(18.00), description: "Car parking")
+ claimItem( dateIncurred: days(-14), amount: money(26.50), description: "Reading - London (return)")
+ }
+ }
+
+ private Date days(int days) {
+ Date date = new Date();
+ date = date.add(0,0, days);
+ return date
+ }
+
+ private Money money(double amount) {
+ return new Money(amount, "USD");
+ }
+}</programlisting>
+
+ <para>The builder is instantiated by passing in the
+ <classname>DomainObjectContainer</classname>, as well as one
+ representative class from each package that holds entities to be built.
+ In this case the <literal>Employee.class</literal> takes care of the
+ <package>employee</package> package (for just
+ <classname>Employee</classname> itself), while
+ <literal>Claim.class</literal> represents the <package>claims</package>
+ package (for both <classname>Claim</classname> and
+ <classname>ClaimItem</classname>).</para>
+
+ <para>The <acronym>DSL</acronym> for building the object graph is just
+ that defined by Groovy's <classname>ObjectGraphBuilder</classname>, and
+ is substantially more succinct than its Java equivalent.</para>
+
+ <para>There is one limitation to be aware of, though, which relates to
+ how the <classname>Claim</classname>/<classname>ClaimItem</classname>
+ parent/child is wired up. It's important for the collection name in the
+ parent (<classname>Claim</classname>) to match that of the class name of
+ the child (<classname>ClaimItem</classname>), and the back reference in
+ the child (if there is one) to match the class name of the parent. For
+ the test app, this means that the collection in
+ <classname>Claim</classname> is called
+ <methodname>claimItems</methodname>. If this is irksome, then the
+ <classname>ObjectGraphBuilder</classname> does define the ability to
+ tweak its behaviour as to how the relationship name is inferred.</para>
+
+ <note>
+ <para>(A future enhancement might be to solve this problem in the
+ general case, by perform the wiring using the
+ <emphasis>Isis</emphasis> metamodel).</para>
+ </note>
+ </chapter>
+ </part>
+
+ <part id="prt.Wrapper">
+ <title>Wrapper Programming Model</title>
+
+ <partintro>
+ <para>*** describe the [oai.progmodels:wrapper] programming
+ model.</para>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title></title>
+
+ <section>
+ <title></title>
+
+ <para></para>
+ </section>
+ </chapter>
+ </part>
+</book>
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/apt/index.apt
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/apt/index.apt b/component/progmodel/groovy/src/site/apt/index.apt
new file mode 100644
index 0000000..fe34cef
--- /dev/null
+++ b/component/progmodel/groovy/src/site/apt/index.apt
@@ -0,0 +1,44 @@
+~~ 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.
+
+Groovy Programming Model
+
+ The <groovy progmodel> configures Apache Isis to allow you to write your domain objects
+ in {{{http://groovy.codehaus.org}Groovy}}.
+
+ The conventions are based on the <default programming> model; the purposes of this
+ programming model is to instruct Isis to ignore synthetic methods created by the
+ Groovy compiler.
+
+Alternatives
+
+ Alternatives include:
+
+ * the {{{../dflt/index.html}default}} programming model.
+
+ For domain objects written with Java.
+
+ * the {{{../wrapper/index.html}wrapper}} programming model.
+
+ This extends the default programming model by providing the ability for domain objects to
+ interact with each other <as if> through the user interface (that is, obeying any business
+ rules that would otherwise be enforced at the application layer).
+
+ []
+
+ Note that these are <not> necessarily mutually exclusive (they can be combined).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/apt/jottings.apt
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/apt/jottings.apt b/component/progmodel/groovy/src/site/apt/jottings.apt
new file mode 100644
index 0000000..c5d1200
--- /dev/null
+++ b/component/progmodel/groovy/src/site/apt/jottings.apt
@@ -0,0 +1,24 @@
+~~ 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.
+
+
+
+Jottings
+
+ This page is to capture any random jottings relating to this module prior
+ to being moved into formal documentation.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/resources/images/HexagonalArchitectureOverview.png
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/resources/images/HexagonalArchitectureOverview.png b/component/progmodel/groovy/src/site/resources/images/HexagonalArchitectureOverview.png
new file mode 100644
index 0000000..fd3db18
Binary files /dev/null and b/component/progmodel/groovy/src/site/resources/images/HexagonalArchitectureOverview.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/resources/images/NO-powered-by-logo.png
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/resources/images/NO-powered-by-logo.png b/component/progmodel/groovy/src/site/resources/images/NO-powered-by-logo.png
new file mode 100644
index 0000000..802db39
Binary files /dev/null and b/component/progmodel/groovy/src/site/resources/images/NO-powered-by-logo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/resources/images/hal-logo-for-maven-site.jpg
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/resources/images/hal-logo-for-maven-site.jpg b/component/progmodel/groovy/src/site/resources/images/hal-logo-for-maven-site.jpg
new file mode 100644
index 0000000..7c508b4
Binary files /dev/null and b/component/progmodel/groovy/src/site/resources/images/hal-logo-for-maven-site.jpg differ
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/groovy/src/site/site.xml
----------------------------------------------------------------------
diff --git a/component/progmodel/groovy/src/site/site.xml b/component/progmodel/groovy/src/site/site.xml
new file mode 100644
index 0000000..87ad7f5
--- /dev/null
+++ b/component/progmodel/groovy/src/site/site.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project name="${project.name}">
+
+ <body>
+ <breadcrumbs>
+ <item name="Groovy" href="index.html"/>
+ </breadcrumbs>
+
+ <menu name="Groovy Support">
+ <item name="About" href="index.html" />
+ <item name="Groovy" href="http://groovy.codehaus.org" />
+ </menu>
+
+ <menu name="Progmodel Modules">
+ <item name="Default (Java)" href="../dflt/index.html" />
+ <item name="Groovy" href="../groovy/index.html" />
+ <item name="Wrapper" href="../wrapper/index.html" />
+ </menu>
+
+ <menu name="Groovy Modules">
+ <item name="Applib" href="./groovy-applib/index.html" />
+ <item name="Metamodel" href="./groovy-metamodel/index.html" />
+ </menu>
+
+ <menu name="Maven Reports" ref="reports" />
+ </body>
+
+</project>
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/NOTICE
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/NOTICE b/component/progmodel/wrapper/NOTICE
new file mode 100644
index 0000000..d391f54
--- /dev/null
+++ b/component/progmodel/wrapper/NOTICE
@@ -0,0 +1,7 @@
+Apache Isis
+Copyright 2010-2011 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/pom.xml
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/pom.xml b/component/progmodel/wrapper/pom.xml
new file mode 100644
index 0000000..20f4efe
--- /dev/null
+++ b/component/progmodel/wrapper/pom.xml
@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.isis</groupId>
+ <artifactId>isis-parent</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ <relativePath>../../../isis-parent/pom.xml</relativePath>
+ </parent>
+
+
+ <groupId>org.apache.isis.progmodels</groupId>
+ <artifactId>wrapper</artifactId>
+
+ <name>Wrapper ProgModel</name>
+
+ <packaging>pom</packaging>
+
+ <properties>
+ <siteBaseDir>.</siteBaseDir>
+ <relativeUrl/>
+ </properties>
+
+ <!-- used in Site generation for relative references. -->
+ <url>http://incubator.apache.org/isis/${relativeUrl}</url>
+
+ <modules>
+ <module>wrapper-applib</module>
+ <module>wrapper-metamodel</module>
+ </modules>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>${maven-project-info-reports-plugin}</version>
+ <inherited>false</inherited>
+ <reportSets>
+ <reportSet>
+ <inherited>false</inherited>
+ <reports>
+ <report>dependency-management</report>
+ <report>plugins</report>
+ <report>modules</report>
+ <report>summary</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+
+
+ <dependencyManagement>
+ <dependencies>
+
+ <dependency>
+ <groupId>org.apache.isis</groupId>
+ <artifactId>applib</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.runtimes.dflt</groupId>
+ <artifactId>runtime</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-metamodel</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ <type>test-jar</type>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.runtimes.dflt</groupId>
+ <artifactId>runtime</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ <type>test-jar</type>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-unittestsupport</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ <scope>test</scope>
+ </dependency>
+
+ <!-- wrapper applib -->
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>wrapper-applib</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>wrapper-applib</artifactId>
+ <version>${project.version}</version>
+ <type>test-jar</type>
+ </dependency>
+
+ <!-- wrapper impl -->
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>wrapper-impl</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/src/site/apt/index.apt
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/src/site/apt/index.apt b/component/progmodel/wrapper/src/site/apt/index.apt
new file mode 100644
index 0000000..3cbbd45
--- /dev/null
+++ b/component/progmodel/wrapper/src/site/apt/index.apt
@@ -0,0 +1,45 @@
+~~ 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.
+
+
+
+Wrapper Programming Model
+
+ The <wrapper> programming model allows a domain object to be "wrapped" so that when another domain object interact with it,
+ it is <as if> through a viewer. That is, if a property or action is unusable on the wrapped domain object, then the
+ calling domain object will be receive an exception indicating the fact.
+
+ The wrapper programming model is provided as an implementation of Isis' <<<DomainObjectContainer>>> interface (in the
+ {{{../../applib/index.html}applib}}.
+ This can be downcast into a <<<WrapperFactory>>>, from which the domain object is wrapped using a {{{http://cglib.sourceforge.net/}CgLib}} proxy.
+ This proxy implements the checks to ensure that the wrapped object is visible, is not disabled, and the interaction is
+ valid ("see it, use it, do it").
+
+Alternatives
+
+ Alternatives include:
+
+ * the {{{../dflt/index.html}default}} programming model.
+
+ * the {{{../groovy/index.html}wrapper}} programming model.
+
+ For domain objects written with Groovy.
+
+ []
+
+ Note that these are <i>not</i> necessarily mutually exclusive (they can be combined).
+
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/src/site/apt/jottings.apt
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/src/site/apt/jottings.apt b/component/progmodel/wrapper/src/site/apt/jottings.apt
new file mode 100644
index 0000000..c5d1200
--- /dev/null
+++ b/component/progmodel/wrapper/src/site/apt/jottings.apt
@@ -0,0 +1,24 @@
+~~ 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.
+
+
+
+Jottings
+
+ This page is to capture any random jottings relating to this module prior
+ to being moved into formal documentation.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/src/site/site.xml
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/src/site/site.xml b/component/progmodel/wrapper/src/site/site.xml
new file mode 100644
index 0000000..f9cf5e7
--- /dev/null
+++ b/component/progmodel/wrapper/src/site/site.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project>
+
+ <body>
+ <breadcrumbs>
+ <item name="Wrapper" href="index.html"/>
+ </breadcrumbs>
+
+ <menu name="Wrapper Progmodel">
+ <item name="About" href="index.html" />
+ <item name="Jottings" href="jottings.html" />
+ </menu>
+
+ <menu name="Progmodel Modules">
+ <item name="Default (Java)" href="../dflt/index.html" />
+ <item name="Groovy" href="../groovy/index.html" />
+ <item name="Wrapper" href="../wrapper/index.html" />
+ </menu>
+
+ <menu name="Wrapper Modules">
+ <item name="Applib" href="./wrapper-applib/index.html" />
+ <item name="Metamodel" href="./wrapper-metamodel/index.html" />
+ </menu>
+
+ <menu name="Maven Reports" ref="reports" />
+ </body>
+</project>
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/NOTICE
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/NOTICE b/component/progmodel/wrapper/wrapper-applib/NOTICE
new file mode 100644
index 0000000..d391f54
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/NOTICE
@@ -0,0 +1,7 @@
+Apache Isis
+Copyright 2010-2011 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/pom.xml
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/pom.xml b/component/progmodel/wrapper/wrapper-applib/pom.xml
new file mode 100644
index 0000000..ab59a24
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/pom.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.isis.progmodels</groupId>
+ <artifactId>wrapper</artifactId>
+ <version>0.3.1-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>wrapper-applib</artifactId>
+ <name>Wrapper ProgModel Applib</name>
+ <description>Wrapper Applib</description>
+
+
+ <!-- shouldn't be needed, but was being built as a pom for some reason -->
+ <packaging>jar</packaging>
+
+ <properties>
+ <siteBaseDir>..</siteBaseDir>
+ <relativeUrl>wrapper-applib/</relativeUrl>
+ </properties>
+
+ <!-- used in Site generation for relative references. -->
+ <url>http://incubator.apache.org/isis/${relativeUrl}</url>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>${maven-project-info-reports-plugin}</version>
+ <inherited>false</inherited>
+ <configuration>
+ <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
+ </configuration>
+ <reportSets>
+ <reportSet>
+ <inherited>false</inherited>
+ <reports>
+ <report>dependencies</report>
+ <report>dependency-convergence</report>
+ <report>plugins</report>
+ <report>summary</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis</groupId>
+ <artifactId>applib</artifactId>
+ </dependency>
+ </dependencies>
+
+</project>
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/DisabledException.java
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/DisabledException.java b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/DisabledException.java
new file mode 100644
index 0000000..b2cc3ff
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/DisabledException.java
@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+
+package org.apache.isis.progmodel.wrapper.applib;
+
+import org.apache.isis.applib.events.InteractionEvent;
+import org.apache.isis.applib.events.UsabilityEvent;
+
+/**
+ * Superclass of exceptions which indicate an attempt to interact with a class
+ * member that is disabled.
+ */
+public class DisabledException extends InteractionException {
+
+ private static final long serialVersionUID = 1L;
+
+ public DisabledException(final InteractionEvent interactionEvent) {
+ super(interactionEvent);
+ }
+
+ @Override
+ public UsabilityEvent getInteractionEvent() {
+ return (UsabilityEvent) super.getInteractionEvent();
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/HiddenException.java
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/HiddenException.java b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/HiddenException.java
new file mode 100644
index 0000000..9d3c451
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/HiddenException.java
@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+
+package org.apache.isis.progmodel.wrapper.applib;
+
+import org.apache.isis.applib.events.InteractionEvent;
+import org.apache.isis.applib.events.VisibilityEvent;
+
+/**
+ * Superclass of exceptions which indicate an attempt to interact with a class
+ * member that is in some way hidden or invisible.
+ */
+public class HiddenException extends InteractionException {
+
+ private static final long serialVersionUID = 1L;
+
+ public HiddenException(final InteractionEvent interactionEvent) {
+ super(interactionEvent);
+ }
+
+ @Override
+ public VisibilityEvent getInteractionEvent() {
+ return (VisibilityEvent) super.getInteractionEvent();
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InteractionException.java
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InteractionException.java b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InteractionException.java
new file mode 100644
index 0000000..3931d05
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InteractionException.java
@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+
+package org.apache.isis.progmodel.wrapper.applib;
+
+import org.apache.isis.applib.ApplicationException;
+import org.apache.isis.applib.Identifier;
+import org.apache.isis.applib.events.InteractionEvent;
+
+public abstract class InteractionException extends ApplicationException {
+
+ private static final long serialVersionUID = 1L;
+
+ private final InteractionEvent interactionEvent;
+
+ public InteractionException(final InteractionEvent interactionEvent) {
+ super(interactionEvent.getReason());
+ this.interactionEvent = interactionEvent;
+ }
+
+ /**
+ * The {@link InteractionEvent event} passed into the
+ * {@link #InteractionException(InteractionEvent) constructor}.
+ *
+ * <p>
+ * Not part of the API, but made available so that subclasses can expose as
+ * the appropriate subtype of {@link InteractionEvent}. This would have been
+ * more obvious to see if {@link InteractionException} was generic, but
+ * generic subclasses of {@link Throwable} are (apparently) not allowed.
+ *
+ * @return
+ */
+ protected InteractionEvent getInteractionEvent() {
+ return interactionEvent;
+ }
+
+ /**
+ * Convenience method that returns the
+ * {@link InteractionEvent#getAdvisorClass() advisor class} of the wrapped
+ * {@link #getInteractionEvent() interaction event}.
+ *
+ * @return
+ */
+ public Class<?> getAdvisorClass() {
+ return interactionEvent.getAdvisorClass();
+ }
+
+ /**
+ * Convenience method that returns the
+ * {@link InteractionEvent#getIdentifier() identifier} of the wrapped
+ * {@link #getInteractionEvent() interaction event}.
+ *
+ * @return
+ */
+ public Identifier getIdentifier() {
+ return interactionEvent.getIdentifier();
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InvalidException.java
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InvalidException.java b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InvalidException.java
new file mode 100644
index 0000000..d8aa401
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/InvalidException.java
@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+
+package org.apache.isis.progmodel.wrapper.applib;
+
+import org.apache.isis.applib.events.InteractionEvent;
+import org.apache.isis.applib.events.ValidityEvent;
+
+/**
+ * Superclass of exceptions which indicate an attempt to interact with an object
+ * or member in a way that is invalid.
+ *
+ * <p>
+ *
+ */
+public class InvalidException extends InteractionException {
+
+ private static final long serialVersionUID = 1L;
+
+ public InvalidException(final InteractionEvent interactionEvent) {
+ super(interactionEvent);
+ }
+
+ @Override
+ public ValidityEvent getInteractionEvent() {
+ return (ValidityEvent) super.getInteractionEvent();
+ }
+
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/255ef514/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/WrapperFactory.java
----------------------------------------------------------------------
diff --git a/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/WrapperFactory.java b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/WrapperFactory.java
new file mode 100644
index 0000000..fe5e7a2
--- /dev/null
+++ b/component/progmodel/wrapper/wrapper-applib/src/main/java/org/apache/isis/progmodel/wrapper/applib/WrapperFactory.java
@@ -0,0 +1,142 @@
+/*
+ * 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.
+ */
+
+package org.apache.isis.progmodel.wrapper.applib;
+
+import java.util.List;
+
+import org.apache.isis.applib.annotation.Hidden;
+import org.apache.isis.applib.events.InteractionEvent;
+import org.apache.isis.progmodel.wrapper.applib.listeners.InteractionListener;
+
+/**
+ * Provides the ability to "wrap" of a domain object such that it can
+ * be interacted with while enforcing the hide/disable/validate rules implies by
+ * the Isis programming model.
+ *
+ * <p>
+ * The "wrap" is a CGLib proxy that wraps the underlying domain
+ * object. The wrapper can then be interacted with as follows:
+ * <ul>
+ * <li>a <tt>get</tt> method for properties or collections</li>
+ * <li>a <tt>set</tt> method for properties</li>
+ * <li>an <tt>addTo</tt> or <tt>removeFrom</tt> method for collections</li>
+ * <li>any action</li>
+ * </ul>
+ *
+ * <p>
+ * Calling any of the above methods may result in a (subclass of)
+ * {@link InteractionException} if the object disallows it. For example, if a
+ * property is annotated with {@link Hidden} then a {@link HiddenException} will
+ * be thrown. Similarly if an action has a <tt>validate</tt> method and the
+ * supplied arguments are invalid then a {@link InvalidException} will be
+ * thrown.
+ *
+ * <p>
+ * In addition, the following methods may also be called:
+ * <ul>
+ * <li>the <tt>title</tt> method</li>
+ * <li>any <tt>defaultXxx</tt> or <tt>choicesXxx</tt> method</li>
+ * </ul>
+ *
+ * <p>
+ * An exception will be thrown if any other methods are thrown.
+ */
+public interface WrapperFactory {
+
+ /**
+ * Whether interactions with the wrapper are actually passed onto the
+ * underlying domain object.
+ *
+ * @see WrapperFactory#wrap(Object, ExecutionMode)
+ */
+ public static enum ExecutionMode {
+ EXECUTE, NO_EXECUTE
+ }
+
+ /**
+ * Provides the "wrapper" of the underlying domain object.
+ *
+ * <p>
+ * If the object has (see {@link #isWrapper(Object)} already been wrapped),
+ * then should just return the object back unchanged.
+ *
+ * @see #addInteractionListener(InteractionListener)
+ */
+ <T> T wrap(T domainObject);
+
+ /**
+ * Same as {@link #wrap(Object)}, except the actual execution occurs only if
+ * the <tt>execute</tt> parameter indicates.
+ *
+ * <p>
+ * Otherwise, will do all the validations (raise exceptions as required
+ * etc.), but doesn't modify the model.
+ */
+ <T> T wrap(T domainObject, ExecutionMode mode);
+
+ /**
+ * Whether the supplied object has been wrapped.
+ *
+ * @param <T>
+ * @param possibleWrapper
+ * - object that might or might not be a wrapper.
+ * @return
+ */
+ <T> boolean isWrapper(T possibleWrapper);
+
+ /**
+ * All {@link InteractionListener}s that have been registered using
+ * {@link #addInteractionListener(InteractionListener)}.
+ */
+ List<InteractionListener> getListeners();
+
+ /**
+ * Registers an {@link InteractionListener}, to be notified of interactions
+ * on all wrappers.
+ *
+ * <p>
+ * This is retrospective: the listener will be notified of interactions even
+ * on wrappers created before the listener was installed. (From an
+ * implementation perspective this is because the wrappers delegate back to
+ * the container to fire the events).
+ *
+ * @param listener
+ * @return
+ */
+ public boolean addInteractionListener(InteractionListener listener);
+
+ /**
+ * Remove an {@link InteractionListener}, to no longer be notified of
+ * interactions on wrappers.
+ *
+ * <p>
+ * This is retrospective: the listener will no longer be notified of any
+ * interactions created on any wrappers, not just on those wrappers created
+ * subsequently. (From an implementation perspective this is because the
+ * wrappers delegate back to the container to fire the events).
+ *
+ * @param listener
+ * @return
+ */
+ public boolean removeInteractionListener(InteractionListener listener);
+
+ public void notifyListeners(InteractionEvent ev);
+
+}