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:22 UTC
[25/51] [partial] ISIS-694: mothballing the docbkx folders.
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/restfulobjects/src/docbkx/guide/isis-restfulobjects-viewer.xml
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/restfulobjects/src/docbkx/guide/isis-restfulobjects-viewer.xml b/mothballed/docbkx/component/viewer/restfulobjects/src/docbkx/guide/isis-restfulobjects-viewer.xml
new file mode 100644
index 0000000..c0b311b
--- /dev/null
+++ b/mothballed/docbkx/component/viewer/restfulobjects/src/docbkx/guide/isis-restfulobjects-viewer.xml
@@ -0,0 +1,1064 @@
+<?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>
+
+ <!-- front matter -->
+
+ <toc></toc>
+
+ <preface id="preface">
+ <title>Preface</title>
+
+ <para><emphasis>Apache Isis</emphasis> is designed to allow programmers
+ rapidly prototype, develop and deploy domain-driven applications. It is
+ made up of a core framework that supports supports variouys viewers, along
+ with <acronym>API</acronym>s and implementations relating to security, the
+ programming model, the runtime (persistence) and profile stores (user
+ preferences). <emphasis>Apache Isis</emphasis> is hosted at the <ulink
+ url="http://incubator.apache.org/isis">Apache Foundation</ulink>, and is
+ licensed under <ulink
+ url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
+ License v2</ulink>.</para>
+
+ <para><emphasis>RestfulObjects for Isis</emphasis>
+ is an Isis viewer
+ <package>[oai.viewer:restfulobjects]</package> that implements the
+ <ulink url="http://restfulobjects.org">Restful Objects</ulink>
+ specification (hosted at <ulink
+ url="http://restfulobjects.org">http://restfulobjects.org</ulink>). This
+ defines a set of RESTful resources, and corresponding <acronym>JSON</acronym>
+ representations, for accessing and manipulating a domain object
+ model.</para>
+
+ <para>The Restful Objects specification defines a means by which
+ implementations can indicate which of its optional features have been
+ implemented (the "version" resource). Isis implements the majority of the
+ spec.</para>
+
+ <sect1>
+ <title>Who this Guide is For</title>
+
+ <para>This guide describes how to use the <emphasis>restfulobjects viewer
+ </emphasis>both in prototype mode and how to deploy it into production
+ as a webapp. It also describes how to use the <emphasis>restfulobjects
+ viewer</emphasis>'s application library
+ <package>[oai.viewer.restfulobjects:applib]</package> to write client-side
+ applications. It is divided into the following chapters:<itemizedlist>
+ <listitem>
+ <para>Introduction</para>
+
+ <para>This chapter briefly introduces the concept of
+ <acronym>REST</acronym> and how it is mapped to the Isis domain
+ model.</para>
+ </listitem>
+
+ <listitem>
+ <para>The RestfulObjects Viewer Modules</para>
+
+ <para>This ....</para>
+ </listitem>
+
+ <listitem>
+ <para>Xxx</para>
+ </listitem>
+
+ <listitem>
+ <para>Xxx</para>
+ </listitem>
+
+ <listitem>
+ <para>Xxx</para>
+ </listitem>
+ </itemizedlist></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.viewer:restfulobjects)</package> refers to the parent module for
+ RestfulObjects viewer. We also use the "oai" abbreviation within package
+ names.</para>
+ </sect1>
+ </preface>
+
+ <!-- main content -->
+
+ <chapter id="chp.Introduction">
+ <title>Introduction</title>
+
+ <abstract>
+ <para>An introduction to <acronym>REST</acronym> and how it maps onto an
+ <emphasis>Apache Isis</emphasis> domain model.</para>
+ </abstract>
+
+ <para>This chapter briefly explains what <acronym>REST</acronym> is, and
+ why you might want to use it. It then explains how the <emphasis>restfulobjects
+ viewer</emphasis> exposes your domain model using
+ <acronym>REST</acronym>.</para>
+
+ <sect1>
+ <title>REST 101</title>
+
+ <para>Web services were introduced as a means for different computer
+ systems to interact by network even though they may be implemented in
+ different technologies and with different implied domain models.
+ <acronym>SOAP</acronym> is probably the best well-known protocol for
+ doing this, though there have been others. These days there is a whole
+ bunch of specifications over and above those for SOAP; together these
+ are typically called <acronym>WS-*</acronym>.</para>
+
+ <para>Whatever; what characterizes the <acronym>WS-*</acronym>
+ implementations is that they expose only a single endpoint to be
+ invoked; in effect just another way of doing a remote procedure call.
+ Put another way, <acronym>WS-*</acronym> -style web services provide an
+ for a verb - "do this for me". In fact, this <acronym>RPC</acronym>
+ endpoint usually accepts many different message types, and uses some
+ sort of dispatcher to route the message so it can be processed
+ correctly.</para>
+
+ <para><acronym>REST</acronym> (standing for <ulink
+ url="http://en.wikipedia.org/wiki/Representational_State_Transfer"><emphasis>REpresentational
+ State Transfer</emphasis></ulink>) in contrast is a style of designing
+ web services that is modelled on the human web sites. Rather than expose
+ a single endpoint, it exposes multiple endpoints. And these endpoints
+ don't represent verbs, they represent things (or nouns). But
+ <acronym>REST</acronym> goes further than this, because it also
+ restricts what we can do with those resources to the standard
+ <acronym>HTTP</acronym> verbs: <acronym>GET</acronym> (read),
+ <acronym>PUT</acronym> (update), <acronym>DELETE</acronym> (er, delete)
+ and <acronym>POST</acronym> (invoke, or change in some way). The first
+ three of these are idempotent (can be invoked multiple times with no
+ side effects). This is an important characteristic for building scalable
+ systems, and is not one that the <acronym>RPC</acronym> approach towards
+ web services supports at all well.</para>
+
+ <para>What happens if we perform an <acronym>HTTP</acronym>
+ <acronym>GET</acronym> on a resource? Well, we get a representation of
+ that resource. <acronym>REST</acronym> doesn't mandate what that
+ representation is, but typical choices are <acronym>JSON</acronym>,
+ <acronym>XHTML</acronym> or a custom <acronym>XML</acronym> dialect. The
+ <emphasis>restfulobjects-viewer</emphasis> of course uses <acronym>JSON</acronym>
+ (<emphasis>J</emphasis>ava<emphasis>S</emphasis>cript
+ <emphasis>O</emphasis>bject <emphasis>N</emphasis>otation) as its
+ representation media type.</para>
+
+ <para>Moreover, <acronym>REST</acronym> emphasises that these resources
+ should be linked together, again analogous to the way that the human web
+ works with hyperlinks. This is sometimes given the (horrible) acronym
+ <acronym>HATEOAS</acronym>: hypertext as the engine of application
+ state.</para>
+
+ <para>So <acronym>REST</acronym> is much more closely associated with
+ the web - and <acronym>HTTP</acronym> in particular - than
+ <acronym>WS-*</acronym> -style web services ever were. But - so the
+ thinking goes - the vast majority of web services are deployed over the
+ web, so why disregard the web's semantics?</para>
+ </sect1>
+
+ <sect1>
+ <title>The Restful Objects Specification</title>
+
+ <para>The <ulink url="http://restfulobjects.org">Restful Objects</ulink>
+ specification defines a set of RESTful resources, and corresponding
+ <acronym>JSON</acronym> representations, for accessing and manipulating
+ a domain object model. Because it is a specification, it allows for
+ multiple implementations. Apache Isis' <emphasis>restfulobjects viewer</emphasis>
+ is one such implementation; another is <ulink
+ url="http://nakedobjects.net">Restful Objects for .NET</ulink>.</para>
+
+ <screenshot>
+ <screeninfo>Restful Objects resources</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/restfulobjects.png" scale="40" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>One of the appeals of <acronym>JSON</acronym> is that it is
+ increasingly being used as a data exchange protocol independent of any
+ particular technology. A <acronym>JSON</acronym> string is directly
+ serializable as a graph of <acronym>JSON</acronym> objects, but there
+ are also libraries for all the main stream platforms (Java, .NET, Ruby,
+ Python) to consume and create <acronym>JSON</acronym>. The
+ <emphasis>restfulobjects viewer</emphasis> therefore opens up a domain objects
+ model for consumption in other languages.</para>
+
+ <para>We do recommend that you download the <emphasis>Restful
+ Objects</emphasis> spec and at least review its introductory chapters
+ (part A). However, given that the spec is pretty close to 200 pages,
+ please don't consider that a mandatory first step. You can get a pretty
+ good idea of what the Isis <emphasis>restfulobjects viewer</emphasis> does just by playing with Isis'
+ quickstart archetype, discussed later.</para>
+ </sect1>
+
+ <sect1 id="sec.IntroducingRestfulObjects">
+ <title>RestfulObjects for Isis as an RO implementation</title>
+
+ <para><emphasis>Restful Objects</emphasis> defines a core set of
+ functionality that all implementations must honour, and also defines a
+ set of capabilities which may be optionally implemented. Implementations
+ indicate the functionality that they support through (the representation
+ of the) "version" resource, specificially the "optionalCapabilities"
+ property map.</para>
+
+ <para>As such, the <emphasis>restfulobjects viewer</emphasis> returns the
+ following representation:</para>
+
+ <para><programlisting>** TODO</programlisting></para>
+
+ <para>See the <emphasis>Restful Objects</emphasis> spec for details on
+ each of these capabilities.</para>
+ </sect1>
+
+ <sect1>
+ <title>The RestfulObjects viewer modules</title>
+
+ <para>In terms of software, the <emphasis>restfulobjects viewer</emphasis>
+ comprises a number of Maven modules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>org.apache.isis.viewer.restfulobjects</para>
+
+ <para>is the parent module; this also has the site and documentation
+ (this guide)</para>
+ </listitem>
+
+ <listitem>
+ <para>org.apache.isis.viewer.restfulobjects-applib</para>
+
+ <para>is a client-side library to simplify the task of writing
+ Java-based applications that consume <emphasis>Restful
+ Objects</emphasis> representations</para>
+ </listitem>
+
+ <listitem>
+ <para>org.apache.isis.viewer.restfulobjects-viewer</para>
+
+ <para>is the server-side implementation of the resources and
+ representations defined by the <emphasis>Restful Objects</emphasis>
+ spec.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>It isn't mandatory to use the client-side library when writing
+ applications; one could equally write a pure Javascript application, for
+ example. However, the client-side library is worth checking out for
+ Java-based applications, for example in an integration scenario. There
+ is further coverage of its API in <xref
+ linkend="chp.WritingClientSideApps" />.</para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title id="chp.Prototyping">Using the QuickStart Archetype and the RestfulObjects
+ Viewer</title>
+
+ <abstract>
+ <para>How to get started prototyping with <emphasis>restfulobjects
+ viewer.</emphasis></para>
+ </abstract>
+
+ <para></para>
+
+ <para>*** using Chrome plugins</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>The easiest way to get started is to run the
+ <emphasis>Isis</emphasis> quickstart archetype (eg as documented on
+ <emphasis>Isis</emphasis>' website). Once you've done this, you'll end up
+ with an set of modules that allow the application to be booted using the
+ <emphasis>restfulobjects viewer</emphasis>. It includes the following
+ modules:</para>
+
+ <programlisting>myapp/pom.xml
+ myapp-dom/pom.xml # domain object model
+ myapp-fixture/pom.xml # fixtures for seeding object store
+ myapp-objstore-dflt/pom.xml # repository implementations for the default object store
+ myapp-webapp/pom.xml # run the application as a webapp using either the HTML viewer or the RestfulObjects viewer
+</programlisting>
+
+ <para>where 'myapp' is the artifactId specified when you ran the <code>mvn
+ archetype:generate</code> goal.</para>
+
+ <para>This chapter describes in more detail the contents of these modules,
+ and then describes how to get started with running the <emphasis>restfulobjects
+ viewer</emphasis> for prototyping purposes.</para>
+
+ <sect1 id="sec.ParentModule">
+ <title>Understanding the Generated Modules</title>
+
+ <para>Before we run the application, let's look at the modules generated
+ for us by the archetype.</para>
+
+ <sect2>
+ <title>The Parent Module</title>
+
+ <para>The parent module includes as an import a reference to the
+ Apache Isis <emphasis>release</emphasis> artifact
+ <package>[oai:release]</package>:</para>
+
+ <programlisting><dependencyManagement>
+ <dependencies>
+
+ <!-- Apache Isis -->
+ <dependency>
+ <groupId>org.apache.isis</groupId>
+ <artifactId>release</artifactId>
+ <version>x.x.x</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ ...
+
+ </dependencies>
+</dependencyManagement></programlisting>
+
+ <para>where <emphasis>x.x.x</emphasis> is the version of
+ <emphasis>Isis</emphasis> that you are using. The <code>scope</code>
+ of <emphasis>import</emphasis> means that all
+ <code><properties></code> of this artifact are imported, and any
+ <code><dependencyManagement>/<dependencies></code> are
+ imported also.</para>
+
+ <para>If you locate the <acronym>POM</acronym> for this artifact (eg
+ by looking in <filename>~/.m2/repository</filename>) then you'll see
+ that it defines:</para>
+
+ <programlisting><properties>
+ <isis.viewer-restful.version>y.y.y</isis.viewer-restful.version>
+ ....
+</properties></programlisting>
+
+ <para>where y.y.y is the corresponding version of the restfulobjects
+ viewer.</para>
+
+ <para>In the <emphasis>release</emphasis> artifact's
+ <code><dependencyManagement></code> section you'll also find the
+ following:</para>
+
+ <programlisting><dependencyManagement>
+ <dependencies>
+ ...
+ <!-- viewer: restfulobjects -->
+ <dependency>
+ <groupId>org.apache.isis.viewer</groupId>
+ <artifactId>restfulobjects</artifactId>
+ <version>${isis.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.viewer</groupId>
+ <artifactId>restfulobjects-applib</artifactId>
+ <version>${isis.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.isis.viewer</groupId>
+ <artifactId>restfulobjects-viewer</artifactId>
+ <version>${isis.version}</version>
+ </dependency>
+ ...
+ </dependencies>
+</dependencyManagement></programlisting>
+
+ <para>The <package>[oai.viewer:restfulobjects]</package> module is the parent
+ for <emphasis>restfulobjects viewer</emphasis>
+ (<code><packaging>pom</packaging></code>). That means that
+ it doesn't provide any Java classesper se. The <emphasis>restfulobjects
+ viewer</emphasis> module <package>[oai.viewer.restfulobjects:viewer]</package>
+ on the other hand does provide a <acronym>JAR</acronym> artifact,
+ being the main implementation of the viewer. The <emphasis>restfulobjects
+ applib</emphasis> module <package>[oai.viewer.restfulobjects:applib]</package>
+ meanwhile is used for writing client-side applications that use an
+ exposed <emphasis>Isis</emphasis> module, the topic of <xref
+ linkend="chp.WritingClientSideApps" />.</para>
+ </sect2>
+
+ <sect2 id="sec.TheViewerRestfulModule">
+ <title>The Webapp Module</title>
+
+ <para>The webapp module generates a <acronym>WAR</acronym> file. In
+ fact, it generates two WAR files; the second is a
+ xxx-jetty-console.war that embeds a Jetty webserver and allows the WAR
+ to be self-hosting.</para>
+
+ <para>The <emphasis>viewer-restfulobjects</emphasis> module inherits from the
+ parent module and so inherits the various definitions of the parent
+ module. And, not surprisingly, its <code><dependencies></code>
+ section includes a reference to the
+ <package>[oai.viewer.restfulobjects:viewer]</package> module.</para>
+
+ <para>More significantly, the <emphasis>viewer-restfulobjects</emphasis> has the
+ standard directory structure for a webapp, with
+ <filename>src/main/webapp/WEB-INF</filename> holding the
+ <filename>web.xml</filename> along with <emphasis>Isis</emphasis>' own
+ configuration files (<filename>isis.properties</filename> and
+ others).</para>
+
+ <para>The following sections look at the <filename>web.xml</filename>
+ in more detail</para>
+
+ <sect3>
+ <title>JAX-RS Configuration</title>
+
+ <para>The <filename>web.xml</filename> defines the following context
+ parameter:</para>
+
+ <programlisting><context-param>
+ <param-name>javax.ws.rs.Application</param-name>
+ <param-value>org.apache.isis.viewer.restfulobjects.viewer.RestfulObjectsApplication</param-value>
+</context-param></programlisting>
+
+ <para>This is used by <emphasis>RestEasy</emphasis> (the underlying
+ <acronym>JAX-RS</acronym> reference implementation) to define the
+ resources to be exposed. (These resources are discussed further in
+ <xref linkend="chp.Resources" />). <emphasis>RestEasy</emphasis>
+ itself is loaded through a context listener:</para>
+
+ <programlisting><listener>
+ <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
+</listener></programlisting>
+
+ <para><emphasis>RestEasy</emphasis> also requires that its servlet
+ is registered:<programlisting><servlet>
+ <servlet-name>RestEasy</servlet-name>
+ <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+...
+<servlet-mapping>
+ <servlet-name>RestEasy</servlet-name>
+ <url-pattern>/</url-pattern>
+</servlet-mapping></programlisting></para>
+ </sect3>
+
+ <sect3>
+ <title>Isis Session handling (using the <emphasis>Default
+ Runtime</emphasis>)</title>
+
+ <para>An <emphasis>Isis</emphasis> session is required in order for
+ the <emphasis>xhtml viewer</emphasis> to interact with the
+ <emphasis>Isis</emphasis> runtime and interrogate the
+ metamodel/retrieve domain objects.</para>
+
+ <para>The first part of the required configuration is to set up an
+ <emphasis>Isis</emphasis> "context"; basically a set of factories
+ that are used to create a session for each subsequent request. This
+ is done using a context listener (defined in the <emphasis>default
+ runtime</emphasis>,
+ <package>[oai.core:isis-core-runtime]</package>):</para>
+
+ <programlisting><listener>
+ <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+</listener></programlisting>
+
+ <para>The session is created for each request using the
+ <classname>IsisSessionFilter</classname>:</para>
+
+ <programlisting><filter>
+ <filter-name>IsisSessionFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+ <init-param>
+ <param-name>authenticationSessionLookupStrategy</param-name>
+ <param-value>org.apache.isis.viewer.restfulobjects.viewer.authentication.AuthenticationSessionLookupStrategyTrusted</param-value>
+ </init-param>
+</filter>
+...
+<filter-mapping>
+ <filter-name>IsisSessionFilter</filter-name>
+ <url-pattern>*</url-pattern>
+</filter-mapping></programlisting>
+
+ <para>Note the <code><init-param></code> for the filter, which
+ defines a strategy for obtaining the authenticationSession (that is,
+ the user's credentials). In the architect specifies a strategy
+ whereby the caller is effectively trusted. However, other strategies
+ can be plugged in as required. This is discussed further in <xref
+ linkend="chp.DeployingRestfulObjectsWebapps" />.</para>
+ </sect3>
+
+ <sect3>
+ <title>Resources</title>
+
+ <para>Finally, the <filename>web.xml</filename> also declares a
+ servlet and a filter which are used for serving up and caching
+ certain supporting resources, most notably Javascript. The
+ Javascript is referenced by the generated <acronym>XHTML</acronym>
+ resources, and allow the web browser to submit RESTful requests
+ using HTTP PUT and HTTP DELETE (as well as the usual HTTP GET and
+ HTTP POST).</para>
+
+ <para>The <classname>ResourceServlet</classname> (defined by
+ <package>[oai.core:webapp]</package>) is used serve up static
+ content from either the classpath or file:</para>
+
+ <programlisting><servlet>
+ <servlet-name>Resource</servlet-name>
+ <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+</servlet>
+...
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.js</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.gif</url-pattern>
+</servlet-mapping>
+<servlet-mapping>
+ <servlet-name>Resource</servlet-name>
+ <url-pattern>*.png</url-pattern>
+</servlet-mapping></programlisting>
+
+ <para>The <classname>ResourceCachingFilter</classname> (also defined
+ by <package>[oai.core:webapp]</package>) is used to decorate any
+ static resources (Javascript, CSS or images) so that they are cached
+ client-side:</para>
+
+ <programlisting><filter>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
+ <init-param>
+ <param-name>CacheTime</param-name>
+ <param-value>86400</param-value>
+ </init-param>
+</filter>
+...
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.js</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.css</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.jpg</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.png</url-pattern>
+</filter-mapping>
+<filter-mapping>
+ <filter-name>ResourceCachingFilter</filter-name>
+ <url-pattern>*.gif</url-pattern>
+</filter-mapping></programlisting>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Running the Viewer</title>
+
+ <para>The viewer can be run in a number of ways.</para>
+
+ <sect2 id="sec.RunningFromTheQuickRunModule">
+ <title>Running from the WebApp Module</title>
+
+ <para>To run the viewer in a prototyping mode (that is, using the
+ standalone <acronym>JAR</acronym> and embedded Jetty webserver), you
+ can either:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>run from the command-line using Maven:</para>
+
+ <programlisting>cd viewer-restfulobjects
+mvn antrun:run -D exec=restfulobjects</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>import into your <acronym>IDE</acronym> and use its in-built
+ support for running Maven goals, and run the above-mentioned
+ goal</para>
+
+ <para>In the case of Eclipse, this support is provided through the
+ <emphasis>m2eclipse</emphasis> plugin.</para>
+ </listitem>
+
+ <listitem>
+ <para>import into the Eclipse <acronym>IDE</acronym> and run using
+ the <filename>.launch</filename> configuration</para>
+
+ <para>Navigate to the <emphasis>quickrun</emphasis> module's
+ <filename>ide/eclipse/launch</filename> directory, select the
+ <filename>quickstart-quickrun-restful.launch</filename>
+ configuration, and use Run > Run As >
+ quickstart-quickrun-restful to launch in regular mode (or Debug
+ > Debug As > quickstart-quickrun-restful to launch in debug
+ mode).</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Running from the Viewer-Restful Module</title>
+
+ <para>To run the viewer as a webapp (that is, by hosting the
+ <acronym>WAR</acronym> in an separate instance of a Jetty web server),
+ you can either:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>run from the command-line using Maven:</para>
+
+ <programlisting>cd webapp
+mvn jetty:run</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>import into your <acronym>IDE</acronym> and use its in-built
+ support for running Maven goals, and run the asbove-mentioned
+ goal</para>
+
+ <para>In the case of Eclipse, this support is provided through the
+ <emphasis>m2eclipse</emphasis> plugin.</para>
+ </listitem>
+
+ <listitem>
+ <para>import into the Eclipse <acronym>IDE</acronym> and run using
+ the <filename>.launch</filename> configuration</para>
+
+ <para>Navigate to the <emphasis>viewer-restful</emphasis> module's
+ <filename>ide/eclipse/launch</filename> directory, select the
+ <filename>quickstart-viewer-restful.launch</filename>
+ configuration, and use Run > Run As >
+ quickstart-viewer-restful to launch in regular mode (or Debug >
+ Debug As > quickstart-viewer-restful to launch in debug
+ mode).</para>
+
+ <note>
+ <para>It's confusing perhaps, but this isn't quite the same as
+ running from the quickrun module: this launch configuration runs
+ the <classname>oai.WebServer</classname> utility class provided
+ by <emphasis>Isis</emphasis> which simply runs up the webapp
+ defined by <filename>web.xml</filename>. The quickrun module, on
+ the other hand, uses the special bridge class discussed in <xref
+ linkend="sec.TheQuickRunModule" />.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>import into your <acronym>IDE</acronym> and use your
+ <acronym>IDE</acronym>'s native support for running
+ webapps.</para>
+
+ <para>In the case of Eclipse, this is its <acronym>WTP</acronym>
+ support (in the enterprise editions).</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Testing the Viewer</title>
+
+ <para>The point of xhtml viewer is to allow the domain objects to be
+ interacted with programmatically through <acronym>HTTP</acronym>, which
+ implies writing a custom client that submits the relevant
+ <acronym>HTTP</acronym> requests. Indeed, this is the topic of <xref
+ linkend="chp.WritingClientSideApps" />.</para>
+
+ <para>However, it is also useful to be able to browse the resources
+ directly, and because they are exposed using XHTML, this is possible to
+ do using a web browser. Therefore, boot up Firefox and browse to <ulink
+ url="http://localhost:8080">http://localhost:8080</ulink>. You should
+ either immediately be connected to the site, or see a link to the
+ context where the site is hosted.</para>
+
+ <note>
+ <para>Firefox is currently the only supported web browser for testing
+ in this way.</para>
+ </note>
+
+ <para>From the site, you should see links to access the services; these
+ are (representations of) the registered services (typically
+ repositories) in <filename>isis.properties</filename> configuration
+ file.</para>
+
+ <para>These structure of the resources is discussed further in <xref
+ linkend="chp.Resources" />.</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="chp.WritingClientSideApps">
+ <title>The RestfulObjects Viewer AppLib</title>
+
+ <abstract>
+ <para>How to write custom client-side applications to consume the
+ RESTful resources using the restfulobjects-viewer's applib.</para>
+ </abstract>
+
+ <para>The point of the <emphasis>restfulobjects viewer</emphasis> is to provide our
+ domain objects as <acronym>REST</acronym>ful resources so that they can be
+ used by any other client application. These applications can be written in
+ any language; so long as they can submit <acronym>HTTP </acronym>requests
+ and can parse <acronym>JSON</acronym>, they can interact with the
+ resources provided by the viewer.</para>
+
+ <para>That said, if you are writing Java applications, then there is also
+ an application library (applib) to simplify the task. To reference this
+ applib, add the following to your Maven pom's
+ <sgmltag><dependencies></sgmltag> section:</para>
+
+ <programlisting>
+<dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.isis.viewer</groupId>
+ <artifactId>restfulobjects-applib</artifactId>
+ <version>${isis.version}</version>
+ </dependency>
+ ...
+</dependencies></programlisting>
+
+ <para>You then have a choice of approaches.</para>
+
+ <sect1>
+ <title><classname>AbstractRestfulClient</classname></title>
+
+ <para>To get you started you might want to use the adapter,
+ <classname>AbstractRestfulClient</classname>, available in the
+ <emphasis>xhtml viewer</emphasis>' applib. This exposes some of the
+ <acronym>HTTP</acronym> methods, including <acronym>GET</acronym> and
+ <acronym>POST</acronym>, and serves up resources as
+ <acronym>XML</acronym> documents (using Elliot Rusty Harold's <ulink
+ url="http://www.xom.nu/">XOM</ulink> library). There is also a
+ <classname>XomUtils</classname> class, that provides some
+ pretty-printing support and a couple of other helper methods.</para>
+
+ <note>
+ <para><classname>AbstractRestfulClient</classname> is not particularly
+ comprehensive (at the time of writing it doesn't include support for
+ <acronym>PUT</acronym> or <acronym>DELETE</acronym>, for example). It
+ may well gain extra methods in future releases, however.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="sec.CodingApproaches">
+ <title><emphasis>RestEasy</emphasis>'s Client-side Framework</title>
+
+ <para>Alternatively, you might want to look into JBoss
+ <emphasis>RestEasy</emphasis>, which provides a <ulink
+ url="http://www.jboss.org/file-access/default/members/resteasy/freezone/docs/1.0.2.GA/userguide/html_single/index.html#RESTEasy_Client_Framework">client-side
+ framework</ulink> to eliminate some of the boilerplate. This uses the
+ resource interfaces (see <xref linkend="chp.Resources" />) to create
+ client-side stubs.</para>
+
+ <note>
+ <para>Due to a fact that <classname>@Path</classname> is annotated on
+ the implementations - not the interfaces - of
+ <classname>ObjectResource</classname>,
+ <classname>ServiceResource</classname>,
+ <classname>SpecsResource</classname> and
+ <classname>UserResource</classname>, it's possible that this approach
+ will not work until we upgrade the version of
+ <emphasis>RestEasy</emphasis>.</para>
+ </note>
+ </sect1>
+
+ <sect1>
+ <title>The Json Viewer AppLib</title>
+
+ <para></para>
+
+ <para>* following links</para>
+
+ <para>* templated URIs vs walker representations</para>
+
+ <para>* following links (format of body)</para>
+
+ <para></para>
+
+ <para>* @Idempotent, @QueryOnly</para>
+
+ <para></para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>The AppLib</title>
+
+ <para>TODO.</para>
+
+ <para></para>
+
+ <para>Topics to discuss:</para>
+
+ <para></para>
+
+ <para></para>
+ </chapter>
+
+ <chapter id="chp.DeployingRestfulObjectsWebapps">
+ <title>Deploying RestfulObjects Viewer Webapps</title>
+
+ <abstract>
+ <para>Guidance on how to deploy Isis using the <emphasis>xhtml
+ viewer</emphasis>.</para>
+ </abstract>
+
+ <para></para>
+
+ <para>*** this material is now more general purpose, and probably should
+ be tidied up and moved to the applib documentation.</para>
+
+ <para></para>
+
+ <para>At some point you'll presumably want to deploy your domain object
+ using <emphasis>xhtml viewer</emphasis> as a webapp. The quickstart
+ archetype already sets up the <package>viewer-restful</package> module
+ that will generate a <acronym>WAR</acronym> file; however, you may want to
+ adjust its configuration in terms of two areas: authentication, and
+ persistence. This chapter discusses these points.</para>
+
+ <para><note>
+ <para>These instructions assume that the xhtml viewer is being
+ deployed using the <emphasis>default runtime</emphasis>
+ <package>(oai.runtimes:dflt)</package>. At the time of writing this is
+ the only runtime available; in the future there may be other runtimes
+ which will have their own specific deployment requirements</para>
+ </note></para>
+
+ <sect1 id="sec.DeploymentType">
+ <title>Deployment Modes</title>
+
+ <para>By default the <classname>IsisWebAppBootstrapper</classname>
+ context listener (described in <xref
+ linkend="sec.TheViewerRestfulModule" />) will bootstrap Isis in the
+ "SERVER" deployment type. This means that an authentication is required,
+ that the sessions will be bound as thread-locals, and that the
+ persistence mechanism will be defaulted appropriately.</para>
+
+ <para>The deployment type can be changed to other settings, though; most
+ notably you may wish to change to SERVER_EXPLORATION or
+ SERVER_PROTOTYPE. This is done using a context parameter:</para>
+
+ <programlisting><context-param>
+ <param-name>deploymentType</param-name>
+ <param-value>SERVER_EXPLORATION</param-value>
+</context-param></programlisting>
+ </sect1>
+
+ <sect1 id="sec.Authentication">
+ <title>Authentication</title>
+
+ <para>The RESTful architecture doesn't have too much to say about
+ authentication, and (at the time of writing) there are no supplementary
+ standards to define how authentication should be implemented. And
+ because <acronym>REST</acronym> runs over <acronym>HTTP</acronym> we
+ don't get any particular support from the network stack either. In fact,
+ because <acronym>HTTP</acronym> is stateless we don't even get the
+ notion of a session or a connection.</para>
+
+ <para>The <emphasis>xhtml viewer</emphasis> therefore uses
+ <emphasis>Isis</emphasis>' own authentication mechanism, with
+ authentication performed for each RESTful call. What this means depends
+ on the deployment type (see <xref
+ linkend="sec.DeploymentType" />):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>if running in SERVER_EXPLORATION mode, then authentication is
+ in effect switched off; no credentials are supplied, and the
+ framework will use the first exploration user defined in
+ <emphasis>isis.properties</emphasis>, or a fallback "exploration"
+ user otherwise</para>
+
+ <para>For example, if running in SERVER_EXPLORATION mode, then you
+ can specify the user using:</para>
+
+ <programlisting>isis.exploration.users=sven:role1, dick:role2, bob:role1|role2</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>otherwise (if running SERVER_PROTOTYPE or SERVER), then
+ authentication credentials are needed.</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>You can if you want run in EXPLORATION (or PROTOTYPE) mode
+ rather than SERVER_EXPLORATION (or SERVER_PROTOTYPE) mode. The
+ difference is that former only support single-users, while SERVER_*
+ supports multiple concurrent users.</para>
+ </note>
+
+ <para>Running the Restful Objects in SERVER mode with no credentials
+ will result in an exception:</para>
+
+ <screenshot>
+ <screeninfo>Server mode, no credentials</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/server-mode-no-credentials.png"
+ scale="40" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>On the other hand, if user and password parameters are supplied,
+ then we can login:</para>
+
+ <screenshot>
+ <screeninfo>Server mode, with credentials</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/server-mode-with-credentials.png"
+ scale="40" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>This behaviour is pluggable however, at two levels:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>IsisSessionFilter</classname> uses the
+ <varname>authenticationManagerLookupStrategy</varname> property to
+ specify a strategy for both finding credentials and for validating
+ them against the <emphasis>Apache Isis</emphasis> authentication
+ manager.</para>
+
+ <para>The <emphasis>xhtml viewer</emphasis> provides two additional
+ implementations of this that you can use:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The
+ <classname>oai.viewer.restful.viewer.authentication.AuthenticationSessionLookupStrategyParams</classname>
+ implementation extends the default behaviour by also looking up
+ credentials using the username and password parameters. Once
+ validated, it also binds the results to the
+ <classname>HttpSession</classname> so that future interactions
+ do not credentials.</para>
+ </listitem>
+
+ <listitem>
+ <para>The
+ <classname>oai.viewer.restful.viewer.authentication.AuthenticationSessionLookupStrategyTrusted</classname>
+ implementation ensures that an (exploration) session is always
+ present (if a session isn't available from the default
+ implementation).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>-
+ <classname>AuthenticationSessionLookupStrategyParams</classname> in
+ the package
+ <classname>org.starobjects.restful.viewer.authentication</classname>
+ -</para>
+
+ <para>In both cases these can be configured using:</para>
+
+ <programlisting><filter>
+ <filter-name>IsisSessionFilter</filter-name>
+ <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+ <init-param>
+ <param-name>authenticationSessionLookupStrategy</param-name>
+ <param-value>org.apache.isis.viewer.restful.viewer.authentication.AuthenticationSessionLookupStrategyTrusted</param-value>
+ </init-param>
+</filter></programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Alternatively, you can change the implementation of
+ <classname>AuthenticationManager</classname> that
+ <emphasis>Isis</emphasis>' delegates to. This is done using the
+ <varname>isis.authentication</varname> key in
+ <filename>isis.properties</filename>:</para>
+
+ <programlisting>isis.authentication=com.mycompany.isis.authentication.MyAuthenticationManagerInstaller</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>In the future there will doubtless be standardized (WS-* style)
+ approaches for RESTful authenticatication, but the above should provide
+ enough flexibility in the meantime.</para>
+
+ <note>
+ <para>Note that the archetype explicitly specifies the authentication
+ mechanism as no-op.</para>
+ </note>
+ </sect1>
+
+ <sect1>
+ <title>Runtime / Persistence</title>
+
+ <para>The persistence mechanism (aka object store) is determined using
+ isis.persistence key in isis.properties. For example, to use the XML
+ object store, you would specify:</para>
+
+ <programlisting>isis.persistor=xml</programlisting>
+
+ <para><note>
+ <para>Note that the archetype explicitly specifies the object store
+ as in-memory.</para>
+ </note></para>
+ </sect1>
+ </chapter>
+</book>
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/changed-object.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/changed-object.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/changed-object.png
new file mode 100644
index 0000000..47ca7c8
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/changed-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/designed-collection.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/designed-collection.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/designed-collection.png
new file mode 100644
index 0000000..2f22c71
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/designed-collection.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-action.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-action.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-action.png
new file mode 100644
index 0000000..b706eb8
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-action.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-edit.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-edit.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-edit.png
new file mode 100644
index 0000000..a88d9df
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-edit.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-object.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-object.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-object.png
new file mode 100644
index 0000000..d06e643
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/generic-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/list-tag.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/list-tag.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/list-tag.png
new file mode 100644
index 0000000..4aae0fd
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/list-tag.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/listing.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/listing.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/listing.png
new file mode 100644
index 0000000..0ef1874
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/listing.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/new-product.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/new-product.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/new-product.png
new file mode 100644
index 0000000..edc32a7
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/new-product.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/object-with-method.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/object-with-method.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/object-with-method.png
new file mode 100644
index 0000000..c51044c
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/object-with-method.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/opening.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/opening.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/opening.png
new file mode 100644
index 0000000..53ef991
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/opening.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7a7836e3/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/table-tag.png
----------------------------------------------------------------------
diff --git a/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/table-tag.png b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/table-tag.png
new file mode 100644
index 0000000..e324c86
Binary files /dev/null and b/mothballed/docbkx/component/viewer/scimpi/src/docbkx/guide/images/example/table-tag.png differ