You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2014/02/12 00:31:24 UTC
[27/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml b/mothballed/docbkx/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
new file mode 100644
index 0000000..86b634a
--- /dev/null
+++ b/mothballed/docbkx/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/7a7836e3/mothballed/docbkx/component/security/src/docbkx/guide/isis-security.xml
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/security/src/docbkx/guide/isis-security.xml b/mothballed/docbkx/component/security/src/docbkx/guide/isis-security.xml
new file mode 100644
index 0000000..5f3bc8b
--- /dev/null
+++ b/mothballed/docbkx/component/security/src/docbkx/guide/isis-security.xml
@@ -0,0 +1,620 @@
+<?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>Robert</firstname>
+
+ <surname>Matthews</surname>
+ </author>
+
+ <author>
+ <firstname>Dan Haywood</firstname>
+ </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>
+
+ <!-- front matter -->
+
+ <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>The security <acronym>API</acronym> covers authentication and
+ authorization. A number of different security implementations, and this
+ guide explains how to configure them, as well as how to go about
+ implementing your own implementation.</para>
+
+ <sect1>
+ <title>Who this Guide is For</title>
+
+ <para>This guide is written for deployers looking to configure
+ <emphasis>Isis</emphasis> to run with a specific existing security
+ implementation, and for programmers wishing to develop their own custom
+ implementation. It is divided into the following parts:<itemizedlist>
+ <listitem>
+ <para>Isis Security Implementations</para>
+
+ <para>This part of the guide (see <xref
+ linkend="prt.IsisImplementations" />) covers the default (Java 5)
+ programming model, how to customize it, and how to extend
+ it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Writing a Custom Implementation</para>
+
+ <para>This part of the guide (see <xref
+ linkend="prt.ImplementingACustomImplementation" />) describes how
+ to go about writing your own custom implementation of the security
+ <acronym>API</acronym>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Configuring the Runtime</para>
+
+ <para>This part of the guide (see <xref
+ linkend="prt.ConfiguringTheRuntime" />) describes how to configure
+ your application to use a specified security
+ implementation.</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
+
+ <sect1>
+ <title>How this Guide relates to other Documentation</title>
+
+ <para>The <emphasis>core</emphasis> documentation
+ <package>[oai:core]</package> describes the security
+ <acronym>API</acronym> as defined by the <emphasis>core
+ runtime</emphasis> <package>[oai.core:runtime]</package>. The runtime
+ documentation (for example the <emphasis>default runtime</emphasis>
+ module <package>[oai.runtimes:dflt]</package>) will describe how to
+ configure security, but for convenience the configuration information is
+ also provided in this guide also.</para>
+ </sect1>
+ </preface>
+
+ <part id="prt.IsisImplementations">
+ <title>Isis Security Implementations</title>
+
+ <partintro>
+ <para><emphasis>Apache Isis</emphasis> applications support
+ authentication ("who are you"?) and authorization ("what can you do?").
+ This allows the set of functionality to be restricted based upon the
+ user's role, with no security knowledge needing to be embedded within
+ the domain objects. </para>
+
+ <para>From the domain objects persepective the user is represented as
+ the <classname>UserMemento</classname> and
+ <classname>RoleMemento</classname> values (in the
+ <package>oai.applib.security</package> package), but within the
+ framework the user is represented by an
+ <classname>AuthenticationSession</classname> object. From this session
+ object can be obtained the name of the user and their roles.</para>
+
+ <para>The security <acronym>API</acronym> is defined in the
+ <emphasis>core runtime</emphasis> module [oai.core:runtime] by the
+ <classname>AuthenticationManager</classname> interface and the
+ <classname>AuthorizationManager</classname> interface. Isis has a number
+ of implementations of both: a default (no-op) implementation, a simple
+ file-based implementation and an <acronym>LDAP</acronym> implementation.
+ The default for the authentication manager depends on the runtime;
+ </para>
+
+ <para>If no authorization manager has been specified, then all domain
+ properties, collections and actions will be available to all users. When
+ an authorization manager is configured, it can be used to authorise the
+ visibility ("can you see it?") and usability ("can you use it?") of
+ properties/collections and actions independently. This is done with
+ respect to the roles that are assigned to the user. Thus an object
+ member may be visible to certain roles but not editable.</para>
+
+ <para>It is possible, if required, to mix-and-match implementations. For
+ example, authentication could be using LDAP, but authorization could be
+ done using file-based implementation or a custom implementation.</para>
+ </partintro>
+
+ <chapter>
+ <title>Default (No-op) Security Implementation</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>***</title>
+
+ <para><emphasis>*** yada yada</emphasis></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.FileIntro">
+ <title>File Security Implementation</title>
+
+ <abstract>
+ <para>A simple file-based security implementation that reads from
+ plain text files that reside in the configuration directory.</para>
+ </abstract>
+
+ <sect1>
+ <title>Authentication</title>
+
+ <para>Authentication grants access to users, and determines their
+ current roles.</para>
+
+ <sect2>
+ <title>The Passwords File</title>
+
+ <para>The file-based authenticator reads the user/passwords and
+ roles from a file called <filename class="directory"
+ moreinfo="none">security_file.password</filename>s. This should
+ reside in the same location as the
+ <emphasis>isis.properties</emphasis> configuration file.</para>
+
+ <para>The format of this file is:</para>
+
+ <programlisting format="linespecific"><user>:<password>:<role>|<role>|...</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Example</title>
+
+ <para>The following example shows how user names (sven and dick) and
+ corresponding passwords (passwd1 and passwd2) should be specified in
+ the password file.</para>
+
+ <programlisting format="linespecific">sven:passwd1:role1|role2
+dick:passwd2:role3</programlisting>
+
+ <para>The user 'sven' has roles 'role1' and 'role2', while 'dick'
+ has 'role3'.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Authorization</title>
+
+ <para>Authorization allows access to actions and properties to be
+ controlled by configuration. </para>
+
+ <sect2>
+ <title>Authorization through 'allow' and 'disallow' files</title>
+
+ <para>With file authorization the current user's role will be
+ authorised against a white and (optionally) a black list for each
+ method possibly available to them. The files are identified by
+ properties, e.g.</para>
+
+ <programlisting format="linespecific">isis.authorization.file.whitelist=security_file.allow
+isis.authorization.file.blacklist=security_file.disallow </programlisting>
+
+ <para>The white list file is mandatory, if there is no property it
+ defaults to <filename>security_file.allow</filename>, and is picked
+ up from the same location as the
+ <filename>isis.properties</filename> configuration file.</para>
+
+ <para>The black list file is optional; the presence of the property
+ indicates it is being used. If the white list file default is being
+ used then we recommend <filename>security_file.disallow</filename>
+ as the name of the black list file. Again, it is picked up from the
+ same location as <filename>isis.properties</filename> configuration
+ file.</para>
+
+ <para>The settings can then be modified to conform to the required
+ security settings.</para>
+ </sect2>
+
+ <sect2>
+ <title>Matching</title>
+
+ <para>Each file contains a signature to match against and a list of
+ roles, which follow the same <itemizedlist>
+ <listitem>
+ <para>A match in the white list file permits the access</para>
+ </listitem>
+
+ <listitem>
+ <para>A match in the black list forbids it the access</para>
+ </listitem>
+
+ <listitem>
+ <para>The black list overrides the white list</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Matching occurs at three levels class, method (or property)
+ and parameters</para>
+
+ <para>Property matches are to the bean property name e.g. 'phone'
+ for getPhone and setPhone.</para>
+ </sect2>
+
+ <sect2>
+ <title>File Format</title>
+
+ <para>The files are formatted as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If only class is to be matched: </para>
+
+ <para><programlisting><fully qualified class> :role1|role2|..</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>If class and method matched: </para>
+
+ <programlisting><fully qualified class>#<method>:role1|role2|..</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If class and property/collection matched:</para>
+
+ <programlisting><fully qualified class>#<property>:role1|role2|..</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If action where method takes no parameters: </para>
+
+ <programlisting><fully qualified class>#<method>():role1|role2|...</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If action where method takes one parameter: </para>
+
+ <programlisting><fully qualified class>#<method>(fully qualified parameter class):role1|role2|...</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If action where method takes two or more
+ parameters:<programlisting><fully qualified class>#<method>(fully qualified parameter class1, fully qualified parameter class2, ...):role1|role2|...</programlisting></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Each line in the file is a separate match.</para>
+
+ <para>There is an optional capability to authorise the visibility
+ and usability of fields independently. Thus a field may be visible
+ to certain roles but not editable. In order to configure this
+ against a authorization a qualifier is added to the role, either
+ "-ro" for read-only (visible) or "-rw" for read/write (visible and
+ usable). For example:</para>
+
+ <programlisting><fully qualified class> :role1-ro|role2-rw|..</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Example</title>
+
+ <para>For example, if in the white list file we have:</para>
+
+ <programlisting format="linespecific">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt:role1 </programlisting>
+
+ <para>then this will permit all actions/properties on <literal
+ moreinfo="none">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt</literal>
+ for role1 to invoke.</para>
+
+ <para>Meanwhile, if we have:</para>
+
+ <programlisting format="linespecific">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt#findClaimantByName:role1-ro|role2-rw</programlisting>
+
+ <para>then this will permit all overloaded methods named <literal
+ moreinfo="none">findClaimantByName</literal> on <literal
+ moreinfo="none">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt</literal>
+ for role1 to view, and for role2 to view and also invoke</para>
+
+ <para>Finally, if we have:</para>
+
+ <programlisting format="linespecific">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt#findClaimantByIdentifier(java.lang.String):role3-rw</programlisting>
+
+ <para>then this will permit <literal
+ moreinfo="none">findClaimantByIdentifier</literal> with parameter
+ <literal moreinfo="none">java.lang.String</literal> on <literal
+ moreinfo="none">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDflt</literal>
+ for role3 to invoke.</para>
+
+ <para>In each case an identical entry in the black list file will
+ instead make the action or property unavailable. </para>
+
+ <para>The combination of white and black list allows some economy in
+ the settings. For example, if all but one method of a large class is
+ to be allowed, that could be configured with one entry per method in
+ the white list file or, better, a single entry for the class in the
+ white list and a single entry for the unavailable method in the
+ black list.</para>
+ </sect2>
+
+ <sect2>
+ <title>Auto-learn</title>
+
+ <para>As a tool for helping to configure the initial security
+ settings there is a 'learn' property.</para>
+
+ <programlisting format="linespecific">isis.authorization.learn=true</programlisting>
+
+ <para>When this is present and set, all methods will be authorised
+ for all roles. However as each method is accessed through the user
+ interface authorization will be configured for that method and the
+ current role. The idea is to these files can then be used as the
+ basis for explicit configuration once auto-learn is disabled.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>LDAP Security Implementation</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <sect1>
+ <title>Authentication</title>
+
+ <para>LDAP needs a URL for the server and a 'dn' of the root of the
+ users on the server. For example,</para>
+
+ <programlisting format="linespecific">isis.authentication.ldap.dn= dc=isis, dc=org </programlisting>
+
+ <programlisting format="linespecific">isis.authentication.ldap.server=ldap://localhost:10389</programlisting>
+
+ <para>The logon password check will be on uid='username', <dn>
+ -</para>
+
+ <para>For example, attempting to logon with user 'sven' with the above
+ settings will check against the server on localhost, port = 10389,
+ uid=sven, dc=isis, dc=org, using the password in the standard <literal
+ moreinfo="none">userpassword</literal> attribute in that entry. Once
+ logged in, roles will be picked up from cn='rolename' where
+ objectclass =organizationalRole in child entries of the user
+ entry.</para>
+ </sect1>
+
+ <sect1>
+ <title>Authorization</title>
+
+ <para>With LDAP authorization the current user's role will be
+ authorised against an entry in the LDAP server for each method
+ possibly available to them. The URL of the server is obtained from the
+ same property as for authentication.</para>
+
+ <para>The authorization entries should exist under a DN configured in
+ the property file. For example.</para>
+
+ <programlisting format="linespecific">isis.authorization.ldap.application.dn= cn=expenses, dc=apps, dc=isis, dc=org </programlisting>
+
+ <para>This will be checked anonymously.</para>
+
+ <para>Entries to be matched against should exist under this dn.
+ Expected configuration is a hierarchy of class, method and parameters.
+ The cn of each entry is expected to be the fully qualified class name,
+ method or parameter list ('()' for an empty parameter list). If an
+ entry has a 'uniquemember' attribute equal to 'role' then that entry
+ and all sub-entries are authorised.</para>
+
+ <para>For example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>DN:
+ cn=org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDefault,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1</para>
+
+ <para>will authorise all members of <literal
+ moreinfo="none">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDefault</literal>
+ for users with role1.</para>
+ </listitem>
+
+ <listitem>
+ <para>DN: cn=(org.apache.isis.expenses.claims.Claimant,
+ java.lang.String), cn=createNewClaim,
+ cn=org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDefault,
+ cn=expenses, dc=apps, dc=isis, dc=org</para>
+
+ <para>with uniquemember = role1</para>
+
+ <para>will authorise the <literal
+ moreinfo="none">createNewClaim(org.apache.isis.expenses.claims.Claimant,
+ String)</literal> member of <literal
+ moreinfo="none">org.apache.isis.expenses.claims.objstoredflt.ClaimRepositoryDefault</literal>
+ for users with role1.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>There is an optional capability to authorise the visibility and
+ usability of fields independently. Thus a field may be visible to
+ certain roles but not editable. In order to configure this against a
+ authorization a flag must be added by setting a "flags" attribute to
+ the entry with the role. <itemizedlist>
+ <listitem>
+ <para>If it is set to 'rw' then editing will be allowed,</para>
+ </listitem>
+
+ <listitem>
+ <para>If it is set to any other value (typically 'ro') then
+ editing is disallowed</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>In each case absence of the flag will mean that visibility and
+ usability and are always the same.</para>
+ </sect1>
+ </chapter>
+ </part>
+
+ <part id="prt.ConfiguringTheRuntime">
+ <title>Configuring the Runtime</title>
+
+ <partintro>
+ <para>***</para>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title>Configuring the Default Runtime</title>
+
+ <abstract>
+ <para>*** yada yada</para>
+ </abstract>
+
+ <para></para>
+
+ <sect1>
+ <title>Exploration Mode</title>
+
+ <para>The list of users that can be switched between during
+ exploration can be listed, separated by commas, using:</para>
+
+ <programlisting format="linespecific">isis.exploration.users=sven, dick, bob</programlisting>
+
+ <para>If no users are specified the default user "exploration" will be
+ used and switching between users will not be possible.</para>
+
+ <para><note>
+ <para>The ability to switch between users also depends on the
+ viewer being used; not every viewer has necessarily implemented
+ this feature.</para>
+ </note></para>
+ </sect1>
+
+ <sect1>
+ <title>No Configuration</title>
+
+ <para></para>
+
+ <para>If no authenticator is configured, then the behaviour depends on
+ the system:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Exploration Mode</para>
+
+ <para>*** yada yada</para>
+ </listitem>
+
+ <listitem>
+ <para>Prototype Mode</para>
+
+ <para>*** yada yada</para>
+ </listitem>
+
+ <listitem>
+ <para>Any other mode</para>
+
+ <para>Defaults to file-based</para>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Configuring Authentication</title>
+
+ <para></para>
+
+ <para>To explicitly use file-based authentication set the following
+ property.</para>
+
+ <programlisting format="linespecific">isis.authentication=file</programlisting>
+
+ <para></para>
+
+ <para>To authenticate through LDAP set</para>
+
+ <programlisting format="linespecific">isis.authentication=ldap</programlisting>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Configuring Authorization</title>
+
+ <para></para>
+
+ <para>To enable authorization within the default runtime, including
+ the facet and specifying the authorization implementation in the
+ settings</para>
+
+ <programlisting format="linespecific">isis.reflector.facets.include=\
+ org.apache.isis.core.runtime.authorization.standard.AuthorizationFacetFactory
+</programlisting>
+
+ <para></para>
+
+ <para>To specify file-based authorization, use:</para>
+
+ <programlisting format="linespecific">isis.authorization=file</programlisting>
+
+ <para></para>
+
+ <para>To specify LDAP-based authorization, use:</para>
+
+ <programlisting format="linespecific">isis.authorization=ldap</programlisting>
+ </sect1>
+ </chapter>
+ </part>
+
+ <part id="prt.ImplementingACustomImplementation">
+ <title>Implementing a custom Security Implementation</title>
+
+ <chapter>
+ <title></title>
+
+ <section>
+ <title></title>
+
+ <para></para>
+ </section>
+ </chapter>
+ </part>
+</book>
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png
new file mode 100755
index 0000000..5f26128
Binary files /dev/null and b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png
new file mode 100755
index 0000000..6ea85b4
Binary files /dev/null and b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png
new file mode 100755
index 0000000..98f7b9a
Binary files /dev/null and b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png
new file mode 100755
index 0000000..7373975
Binary files /dev/null and b/mothballed/docbkx/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png differ