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:46 UTC
[49/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/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
deleted file mode 100644
index 86b634a..0000000
--- a/component/progmodel/groovy/src/docbkx/guide/isis-progmodels.xml
+++ /dev/null
@@ -1,1293 +0,0 @@
-<?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/component/security/src/docbkx/guide/isis-security.xml
----------------------------------------------------------------------
diff --git a/component/security/src/docbkx/guide/isis-security.xml b/component/security/src/docbkx/guide/isis-security.xml
deleted file mode 100644
index 5f3bc8b..0000000
--- a/component/security/src/docbkx/guide/isis-security.xml
+++ /dev/null
@@ -1,620 +0,0 @@
-<?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/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png
----------------------------------------------------------------------
diff --git a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png b/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png
deleted file mode 100755
index 5f26128..0000000
Binary files a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-graphics.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png
----------------------------------------------------------------------
diff --git a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png b/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png
deleted file mode 100755
index 6ea85b4..0000000
Binary files a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-system.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png
----------------------------------------------------------------------
diff --git a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png b/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png
deleted file mode 100755
index 98f7b9a..0000000
Binary files a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-view.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png
----------------------------------------------------------------------
diff --git a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png b/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png
deleted file mode 100755
index 7373975..0000000
Binary files a/component/viewer/dnd/impl/src/docbkx/guide/images/debug-viewer.png and /dev/null differ