You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2011/06/15 14:51:16 UTC
svn commit: r1136015 [2/2] -
/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml
Modified: incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml
URL: http://svn.apache.org/viewvc/incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml?rev=1136015&r1=1136014&r2=1136015&view=diff
==============================================================================
--- incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml (original)
+++ incubator/isis/trunk/runtimes/dflt/src/docbkx/guide/isis-default-runtime.xml Wed Jun 15 12:51:16 2011
@@ -81,29 +81,29 @@
<para>This guide is written for deployers looking to configure
<emphasis>Isis</emphasis> to run using the default runtime, in any of
- the supported configurations. It is divided into the following
- parts:<itemizedlist>
+ the supported configurations. It is divided into two parts:<itemizedlist>
<listitem>
- <para>Core Concepts</para>
+ <para>Users' Guide</para>
- <para>The chapters in this part of the guide <xref
- linkend="prt.CoreConcepts" /> describe the core concepts
- underpinning the design of the <emphasis>default
- runtime</emphasis>.</para>
- </listitem>
-
- <listitem>
- <para>Runtime Modules</para>
-
- <para>This part of the guide has chapters for each of the modules
- that make up the <emphasis>default runtime</emphasis>.</para>
+ <para>The chapters in this part of the guide are written for the
+ developer who wants to just use the <emphasis>default
+ runtime</emphasis> in their own domain applications. It describe
+ how to run applications that use the <emphasis>default
+ runtime</emphasis> in the development environment, how to
+ configure the <emphasis>default runtime</emphasis>, and how to
+ deploy applications in the various different ways using the
+ <emphasis>default runtime</emphasis>.</para>
</listitem>
<listitem>
- <para>Deployment</para>
+ <para>Contributors' Guide</para>
- <para>The chapters in this part of the guide describe different
- ways to deploy an Isis application using the <emphasis>default
+ <para>The chapters in this part of the guide are written for those
+ Isis contributors who want to enhance, improve or otherwise change
+ the <emphasis>default runtime</emphasis> itself They describe the
+ core concepts underpinning the design of the <emphasis>default
+ runtime</emphasis>, and provide a walk through of each of the
+ modules that make up the <emphasis>default
runtime</emphasis>.</para>
</listitem>
</itemizedlist></para>
@@ -115,1403 +115,1998 @@
<para>The <emphasis>core</emphasis> documentation
<package>[oai:core]</package> describes common modules, including
reusable classes that make up the <emphasis>core runtime</emphasis>
- <package>[oai.core:runtime]</package>. This module, the default runtime,
- makes use of these classes, as well as other components. It also defines
- a number of its own <acronym>sub-API</acronym>s.</para>
+ <package>[oai.core:runtime]</package>. This module, the
+ <emphasis>default runtime</emphasis>, makes use of these classes, as
+ well as other components. It also defines a number of its own
+ <acronym>sub-API</acronym>s.</para>
</sect1>
</preface>
- <part id="prt.CoreConcepts">
- <title>Core Concepts</title>
+ <part>
+ <title>Users Guide</title>
<partintro>
- <para></para>
- </partintro>
+ <para>This part of the guide is written for developers who wish to run
+ their own Isis domain applications using the <emphasis>default
+ runtime</emphasis>, and wish to configure the default runtime for their
+ own particular application.</para>
- <chapter>
- <title>Core Concepts</title>
+ <para>The chapters are organized as follows:</para>
- <abstract>
- <para>The core concepts that make up the default runtime
- implementation.</para>
- </abstract>
+ <itemizedlist>
+ <listitem>
+ <para>getting started (in the development environment)</para>
- <para>The role of the runtime component within <emphasis>Isis</emphasis>
- is to bootstrap the application and components, and to manage the
- lifecycle of domain object entities. Typically, this means managing
- their persistence and identity. The default runtime implementation
- <package>[oai.runtimes:dflt]</package> provides support for this, and
- additionally provides support for client/server remoting and also the
- concept of a profilestore.</para>
+ <para>how to run an <emphasis>Isis</emphasis> application using the
+ default runtime within the development environment</para>
+ </listitem>
- <para>Because the scope of the <emphasis>default runtime</emphasis>
- includes remoting, it necessarily adds a degree of abstraction that,
- perhaps, might not otherwise be required. This chapter explains the main
- concepts defined or implemented by the <emphasis>default
- runtime</emphasis>.</para>
+ <listitem>
+ <para>deploying as a webapp</para>
- <sect1>
- <title>Components of the Default Runtime</title>
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a web application (using one of the
+ <emphasis>Isis</emphasis> web viewers)</para>
+ </listitem>
- <para>As will be clear if you've explored the codebase, the
- <emphasis>default runtime</emphasis> implementation consists of a main
- <emphasis>runtime</emphasis>
- module<package>[oai.runtimes.dflt:runtime]</package> along with a
- fairly large number of submodules.</para>
+ <listitem>
+ <para>deploying in standalone mode</para>
- <para>The main <emphasis>runtime</emphasis> module provides the
- following functionality:</para>
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a standalone application (using the DnD viewer or
+ similar)</para>
+ </listitem>
+
+ <listitem>
+ <para>deploying in client/server mode</para>
+
+ <para>How to take an <emphasis>Isis</emphasis> application and
+ deploy it as a client/server application (using the DnD viewer or
+ similar for the client, and another instance of the application
+ running as the server)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para></para>
+ </partintro>
+
+ <chapter>
+ <title>Getting Started</title>
+
+ <para>This chapter assumes that you have an application that has been
+ generated using the Maven quickstart archetype. This archetype generates
+ an application that is preconfigured to run using the <emphasis>default
+ runtime</emphasis>, so some of what is documented here will already have
+ been set up.</para>
+
+ <sect1 id="sec.RuntimeLauncher">
+ <title>Launching <classname>Isis</classname></title>
+
+ <para>The <emphasis>default runtime</emphasis> provides several
+ different mechanisms by which to launch an <emphasis>Apache
+ Isis</emphasis> application.</para>
<itemizedlist>
<listitem>
- <para>classes to bootstrap the default runtime</para>
- </listitem>
+ <para>the first is the <classname>org.apache.isis.Isis</classname>
+ command line runner.</para>
- <listitem>
- <para>the "installer" registry; a repository of components that
- can be bootstrapped</para>
+ <para>This allows Isis to be run from the command line, with the
+ <acronym>UI</acronym> to use being specified by the
+ <code>--viewer</code> flag.</para>
</listitem>
<listitem>
- <para>implementations of the
- <classname>AuthenticationManager</classname> and
- <classname>AuthorizationFacetFactory</classname> interfaces for
- the default runtime</para>
+ <para>the second is the
+ <classname>org.apache.isis.WebServer</classname> webapp
+ runner.</para>
+
+ <para>This is intended to be used only with Maven modules that are
+ structured as a webapp; specifically, with a
+ <filename>src/main/webapp/WEB-INF/web.xml</filename> file.</para>
+
+ <para>The <classname>WebServer</classname> class is completely
+ generic, so in principle this <filename>web.xml</filename> could
+ contain any servlets etc. To use <emphasis>Isis</emphasis>,
+ though, it will typically contain the
+ <classname>oai.runtimes.dflt.webapp.IsisWebAppBootstrapper</classname>
+ (a <classname>javax.servlet.ServletContextListener</classname>),
+ along with the
+ <classname>oai.runtimes.dflt.webapp.IsisSessionFilter</classname>
+ (<classname>a javax.servlet.Filter</classname>)<footnote>
+ <para>We say "typically"; however some of the web-based
+ viewers have their own, equivalent, mechanisms. For example,
+ the <emphasis>Wicket viewer</emphasis>
+ <package>[oai.viewer:wicket]</package> provides a custom
+ subclass of the org.apache.wicket.Application for
+ bootstrapping, while the <emphasis>Restful viewer</emphasis>
+ is bootstrapped using the
+ <classname>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</classname>,
+ providing a custom subclass of
+ <classname>javax.ws.rs.core.Application</classname> to
+ register with Resteasy.</para>
+ </footnote>.</para>
</listitem>
<listitem>
- <para>an abstract <classname>PersistenceSession</classname>
- <acronym>API</acronym> that provides a very generalized means for
- managing the lifecycle of domain objects</para>
-
- <para>This includes an <classname>ObjectFactory</classname> API
- which (in conjunction with the
- <classname>ClassSubstitor</classname> interface defined in the
- <package>[oai.core:metamodel]</package> module) provides hook-in
- points for bytecode enhancement libraries (discussed further
- below);</para>
+ <para>the third option also applies only for webapps, and is
+ simply to run using your IDE's built-in support for hosting
+ webapps. For example, if using Eclipse then this is the <ulink
+ url="http://eclipse.org/webtools">Eclipse WTP</ulink>
+ support.</para>
</listitem>
<listitem>
- <para>an implementation of the
- <classname>PersistenceSession</classname> <acronym>API</acronym>
- which does some of the common work for persistence management and
- defines its own object store <acronym>API</acronym></para>
+ <para>and the final option is similar, and also applies only to
+ webapps, namely to run the webapp from Maven using <code>mvn
+ jetty:run</code> plugin.</para>
</listitem>
+ </itemizedlist>
- <listitem>
- <para>a mechanism to define the set of application domain services
- to make available to the domain objects</para>
- </listitem>
+ <para>Both <classname>org.apache.isis.Isis</classname> and
+ <classname>org.apache.isis.WebServer</classname> classes have main()
+ methods meaning that they are run from the command line. If you have
+ run the archetype then you'll find that there are Eclipse IDE launch
+ configurations for both <classname>oai.Isis</classname> and
+ <classname>oai.WebRunner</classname> (in the
+ <filename>ide/eclipse/launch</filename> directories).</para>
+
+ <para>These two runners act as follows:</para>
+ <itemizedlist>
<listitem>
- <para>a mechanism to define the set of fixtures to automatically
- install into the object store (for use when testing or
- prototyping)</para>
+ <para>start up the logging so that log messages are never
+ lost;</para>
</listitem>
<listitem>
- <para>a mechanism (<classname>Memento</classname>) for capturing
- the state of domain objects over time</para>
+ <para>load up all the installers (component factories) that can be
+ found on the classpath from the
+ <filename>installer-registry.properties</filename> file.
+ (Physically this is packaged within the
+ [oai.runtimes.dflt:runtime] module's
+ <acronym>JAR</acronym>).</para>
+
+ <para>This allow the runner class to be aware of all the
+ components that are available;</para>
</listitem>
<listitem>
- <para>support for more easily building <acronym>XML</acronym>
- snapshots (using the
- <classname>oai.applib.snapshot.Snapshottable</classname>
- interface)</para>
+ <para>parse the command line flags;</para>
+
+ <para>If there is problem with these then a help text is displayed
+ list all the options and the program exits</para>
</listitem>
<listitem>
- <para>a means of storing user preference / profile information
- (including, for example, bookmarks to objects).</para>
+ <para>with the command line flags processed, initialize the
+ installers and bootstraps the system.</para>
</listitem>
</itemizedlist>
- <para>The rest of the <emphasis>default runtime</emphasis>
- (sub)modules provide implementations of the major
- <acronym>API</acronym>s that the <emphasis>default runtime</emphasis>
- exposes:</para>
+ <para>The next section lists the command line flags supported by these
+ two runners.</para>
+ </sect1>
- <itemizedlist>
- <listitem>
- <para>object store</para>
+ <sect1>
+ <title>Command Line Flags</title>
- <para>The object store <acronym>API</acronym> defines a
- persistence mechanism for storing domain objects. Examples include
- a simple in-memory object store (useful only for prototyping), an
- <acronym>XML</acronym> objectstore, a simple
- <acronym>SQL</acronym> objectstore, and a "NoSQL" (JSON-based)
- objectstore.</para>
- </listitem>
+ <para>The following table summarises the command line-flags common to
+ both <classname>org.apache.isis.Isis</classname> commandline runner as
+ well as the <classname>org.apache.isis.WebServer</classname> webapp
+ runner utility.</para>
- <listitem>
- <para>bytecode enhancement</para>
+ <note>
+ <para>Internally, all options are handled by subclasses of the
+ <classname>oai.core.runtime.optionhandler.OptionHandler</classname>
+ interface.</para>
+ </note>
- <para>Bytecode enhancement classes provide the ability to support
- lazy loading while walking a graph from one domain object to
- another, using tools such as <ulink
- url="http://cglib.sourceforge.net">cglib</ulink> or <ulink
- url="http://www.javassist.org">javassist</ulink>. This is a
- similar technique to that employed by <acronym>ORM</acronym>s, but
- is available even if the object store involved does not support
- lazy loading.<footnote>
- <para>Indeed, ORM-based object stores (are likely to) require
- the bytecode providers to be disabled.</para>
- </footnote></para>
+ <para><table>
+ <title>Common command line flags</title>
- <para>The bytecode enhancement is also used for automatic tracking
- of dirty objects (so that Isis knows to flush them to the object
- store at the end of the transaction). The primary
- <acronym>API</acronym> that supports bytecode enhancement is
- <classname>ObjectFactory</classname>, discussed in <xref
- linkend="sec.SessionLevelScope" />.</para>
- </listitem>
+ <tgroup cols="6">
+ <colspec align="center" />
- <listitem>
- <para>profile store</para>
+ <colspec colwidth="10%" />
- <para>The profile store <acronym>API</acronym> defines a
- persistence mechanism for storing user profile information.
- Examples include a simple in-memory profile store (useful only for
- prototyping and testing), and an <acronym>XML</acronym>
- profilestore.</para>
- </listitem>
+ <colspec />
- <listitem>
- <para>client/server remoting support</para>
+ <colspec />
- <para>The <emphasis>default runtime</emphasis> also provides
- support for client/server remoting, through an alternative
- implementation of the <classname>PersistenceSession</classname>
- <acronym>API</acronym><footnote>
- <para>Alternative, that is, to the
- <classname>PersistenceSession</classname> implementation for
- object stores.</para>
- </footnote>.</para>
+ <colspec />
- <para>For example, the DnD viewer can be configured to act as a
- client, holding a cache of domain objects client-side.
- Interactions with these domain objects are sent transparently
- across to a server running the same application domain classes;
- the changes are performed server-side and the results sent back
- down to the client where the results are merged.</para>
- </listitem>
- </itemizedlist>
+ <colspec />
- <para>In addition, because many of the <emphasis>Isis</emphasis>
- viewers are webapps, the <emphasis>default runtime</emphasis> also
- has:</para>
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
- <itemizedlist>
- <listitem>
- <para>a module <package>[oai.runtimes.dflt:webapp]</package> with
- <classname>ServletContextListener</classname> and
- <classname>javax.servlet.Filter</classname> implementations to
- allow <emphasis>Isis</emphasis> to be bootstrapped from a
- webapp</para>
- </listitem>
+ <entry align="center">Long form</entry>
- <listitem>
- <para>provides a convenience module
- <package>[oai.runtimes.dflt:webserver]</package> that provides a
- command-line utility to allow any Maven webapp-structured project
- to be hosted within Jetty.</para>
- </listitem>
- </itemizedlist>
- </sect1>
+ <entry align="center">Purpose</entry>
- <sect1 id="sec.InstallerLookup">
- <title><classname>InstallerLookup</classname> and
- <filename>installer-registry.properties</filename></title>
+ <entry align="center">Typical values</entry>
- <para>The <emphasis>Isis</emphasis> core modules
- <package>[oai:core]</package> already provide the
- <classname>oai.core.commons.components.Installer</classname> interface
- which defines a factory interface for any component within
- <emphasis>Isis</emphasis>.</para>
+ <entry align="center">Default value</entry>
- <para>The <emphasis>default runtime</emphasis> builds upon this
- infrastructure by providing the <classname>InstallerLookup</classname>
- interface (in
- <package>oai.runtimes.dflt.runtime.installerregistry</package>) to act
- as a registry of all available <classname>Installer</classname>s that
- have been bootstrapped. It also provides an implementation,
- <classname>InstallerLookupDefault</classname>, which looks up the
- implementations from the
- <filename>installer-registry.properties</filename> file. This registry
- file can be found in <package>oai.runtimes.dflt.runtime</package>
- package. If no implementation is specified, then a default (defined in
- <package>oai.runtimes.dflt.runtime.system.SystemConstants</package>)
- is used. For some components the specified
- <classname>DeploymentType</classname> will cause the default to vary;
- for example, the default persistence mechanism when running in
- exploration mode is to use the in-memory object store; otherwise
- though the XML object store is defaulted.</para>
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
- <para>In addition to loading components, the
- <classname>InstallerLookupDefault</classname> also updates the
- (mutable) <classname>IsisConfigurationBuilder</classname>, from which
- an <classname>IsisConfiguration</classname> is snapshotted. It does
- this by asking each <classname>Installer</classname> for its
- configuration files
- (<methodname>Installer#getConfigurationResources()</methodname>). For
- those installers that inherit from
- <classname>oai.core.commons.config.InstallerAbstract</classname> (ie
- most if not all of them), this returns a collection of two file names
- that follow the convention:</para>
+ <tbody>
+ <row>
+ <entry>-t <emphasis>deploymenttype</emphasis></entry>
- <itemizedlist>
- <listitem>
- <para><filename>type.properties</filename></para>
- </listitem>
+ <entry>--type</entry>
- <listitem>
- <para><filename>type_name.properties</filename></para>
- </listitem>
- </itemizedlist>
+ <entry>The deployment mode; influences other settings and
+ defaults.</entry>
- <para>For example, if loading the XML persistence mechanism/object
- store this will search for <filename>persistor.properties</filename>
- and then <filename>persistor_xml.properties</filename>.</para>
+ <entry><emphasis>exploration</emphasis>,
+ <emphasis>prototype</emphasis>, <emphasis>client,
+ singleuser, server_exploration, server_prototype, server,
+ utilty</emphasis></entry>
- <para>It's worth pointing out that
- <classname>InstallerLookupDefault</classname> is, in turn, defaulted
- from <classname>IsisModule</classname>. This is an implementation if a
- <classname>com.google.inject.Module</classname>, meaning that
- <emphasis>Isis</emphasis> is, in fact, ultimately bootstrapped by
- <ulink url="http://code.google.com/p/google-guice/">Google
- Guice</ulink><footnote>
- <para>At least, when the <emphasis>default runtime</emphasis> is
- used.</para>
- </footnote>.</para>
- </sect1>
+ <entry><emphasis>prototype</emphasis></entry>
- <sect1>
- <title>Component Scopes</title>
+ <entry>Value corresponds to lower case form of
+ <classname>DeploymentType</classname> class. If running
+ under <classname>WebServer</classname>, should only use
+ <emphasis>server_xxx</emphasis> values. Some viewers (eg the
+ wicket viewer) may define additional deployment types.
+ </entry>
+ </row>
- <para>The components loaded by <classname>InstallerLookup</classname>
- are thread-safe singletons with application (global) scope. From them
- the <emphasis>Isis</emphasis> runtime instantiates further components
- at session, and within that transaction-level scope. This is shown
- below:</para>
+ <row>
+ <entry>-v <emphasis>viewername</emphasis></entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/architecture.png" scale="45" />
- </imageobject>
- </mediaobject>
+ <entry>--viewer</entry>
- <para>For webapp-based viewers, an <classname>IsisSession</classname>
- is instantiated at the beginning of the HTTP request, and is
- automatically closed at the end of the request. In this regard it is
- very similar to the concept of a <acronym>JPA
- </acronym><classname>javax.persistence.PersistenceContext</classname>
- or <ulink url="http://hibernate.org">Hibernate</ulink>
- <classname>org.hibernate.Session</classname>.</para>
+ <entry>Specifies the user interface (viewer
+ implementation).</entry>
- <para>For client/server deployments, an
- <classname>IsisSession</classname> is similar for the server, but for
- the client an <classname>IsisSession</classname> is started when the
- user starts the client, and is only closed when the user quits
- out.<footnote>
- <para>There are, arguably, some issues with this design. In the
- future we may deprecate this design in favour of a design of
- client that is wholly stateless.</para>
- </footnote></para>
+ <entry><emphasis>dnd</emphasis>, <emphasis>html</emphasis>,
+ <emphasis>restful</emphasis>, or FQCN that implements
+ <classname>ViewerInstaller</classname>. can also specify
+ <emphasis>encoding-http, encoding-sockets,
+ serializing-sockets, xstream-sockets</emphasis></entry>
- <para>As the diagram illustrates, an
- <classname>IsisSession</classname> can give rise to one or multiple
- <classname>IsisTransaction</classname>s. If running within a webapp or
- the server-side of a client/server remoting, each
- <classname>IsisSession</classname> will instantiate precisely one
- <classname>IsisTransaction</classname>, automatically begun at the
- beginning of the session and committed at the end. On the client-side
- of a client/server deployment, an
- <classname>IsisTransaction</classname> is created for each
- client/server interaction.</para>
+ <entry><emphasis>dnd</emphasis></entry>
- <para>The following look at the role of each of the components shown,
- in each scope.</para>
+ <entry><para>Values are taken from
+ <filename>installer-registry.properties</filename>. See also
+ <xref
+ linkend="sec.ClientConnectorVsViewer" /></para></entry>
+ </row>
- <sect2>
- <title>Application-level scope</title>
+ <row>
+ <entry>-r <emphasis>persistorname</emphasis></entry>
- <para>The <classname>IsisSystem</classname> is the top-level object
- that represents the running <emphasis>Isis</emphasis> instance.
- Within this top-level object are a number of subsidiary
- objects:</para>
+ <entry>--persistor</entry>
- <itemizedlist>
- <listitem>
- <para>the <classname>DeploymentType</classname> is used to
- categorise the "mode" in which <emphasis>Isis</emphasis> is
- being used. This combines two different dimensions: whether
- <emphasis>Isis</emphasis> is running in a server (multiuser) or
- client context, and whether it is running in
- exploration/prototyping/production. The
- <classname>DeploymentType</classname> in effect can influence
- which implementation of components are created (see <xref
- linkend="sec.InstallerLookup" />).</para>
- </listitem>
+ <entry>The persistence mechanism (ie object store
+ implementation) to use for persisting domain objects between
+ runs.</entry>
- <listitem>
- <para>the <classname>IsisConfiguration</classname> is the final
- configuration after all components have been
- loaded;eLoade</para>
- </listitem>
+ <entry><emphasis>in-memory, xml, sql, nosql, fileserver,
+ mongodb</emphasis>, or FQCN that implements
+ <classname>PersistenceMechanismInstaller</classname>.</entry>
- <listitem>
- <para>the <classname>IsisSessionFactory</classname> is used to
- create <classname>IsisSession</classname>s as required (more on
- this below)</para>
- </listitem>
+ <entry>depends upon the deployment type, eg is
+ <emphasis>in-memory</emphasis> for
+ <emphasis>exploration</emphasis>, or
+ <emphasis>xml</emphasis> if
+ <emphasis>server</emphasis>.</entry>
- <listitem>
- <para>the <classname>LogonFixture</classname> allows automatic
- logon if running with a test/exploration mode
- (<classname>DeploymentType</classname>)</para>
- </listitem>
- </itemizedlist>
+ <entry>Ignored if deployment type is
+ <emphasis>client</emphasis>. Values are taken from
+ <filename>installer-registry.properties</filename> </entry>
+ </row>
- <para>Of the above top-level objects, the
- <classname>IsisSessionFactory</classname> is by far the most
- important, because it is responsible for creating
- <classname>IsisSession</classname>s as and when required. There are
- several elements to an <classname>IsisSession</classname>, and so
- <classname>IsisSessionFactory</classname> delegates the
- instantiation of these elements to its own subsidiary
- objects:</para>
+ <row>
+ <entry>-e <emphasis>profilestorename</emphasis></entry>
- <itemizedlist>
- <listitem>
- <para>The <classname>AuthenticationManager</classname> is used
- for authenticated users into the system, and is used to
- instantiate an <classname>AuthenticationSession</classname>.
- This is discussed further in <xref
- linkend="sec.SessionLevelScope" />.</para>
- </listitem>
+ <entry>--user-profile-store</entry>
- <listitem>
- <para>The <classname>PersistenceSessionFactory</classname> is
- used to instantiate the corresponding
- <classname>PersistenceSession</classname>. This is discussed
- further in <xref linkend="sec.SessionLevelScope" />.</para>
- </listitem>
- </itemizedlist>
+ <entry>The profile store implementation to use for
+ persisting user profile data between runs.</entry>
- <para>In addition, the <classname>IsisSessionFactory</classname>
- holds references to a number of other top-evel components, namely
- <classname>AuthorizationManager</classname>, the
- <classname>SpecificationLoader</classname> (ie the Isis metamodel),
- the <classname>TemplateImageLoader</classname> (for loading
- images/icons) and the <classname>UserProfileLoader</classname>
- (responsible for interacting with the profile store
- component).</para>
- </sect2>
+ <entry><emphasis>in-memory, xml</emphasis>, or FQCN that
+ implements
+ <classname>UserProfileStoreInstaller</classname>.</entry>
- <sect2 id="sec.SessionLevelScope">
- <title>Session-level scope</title>
+ <entry>depends upon the deployment type, eg is
+ <emphasis>in-memory</emphasis> for
+ <emphasis>exploration</emphasis>, or
+ <emphasis>xml</emphasis> if
+ <emphasis>server</emphasis>.</entry>
- <para>The <classname>AuthenticationSession</classname> holds the
- credentials (basically: username and roles) of the user that is
- currently (ie with respect to the current
- <classname>IsisContext</classname>) interacting with
- <emphasis>Isis</emphasis>. In principal this information could
- change over time; for example a user might be added or removed from
- roles.</para>
+ <entry>Values are taken from
+ <filename>installer-registry.properties</filename></entry>
+ </row>
- <para>The <classname>PersistenceSession</classname>, on the other
- hand, is a somewhat more complex beast, consisting in turn
- of:</para>
+ <row>
+ <entry>-x <emphasis>connectorname</emphasis></entry>
- <itemizedlist>
- <listitem>
- <para><classname>IsisTransactionManager</classname>, which is
- responsible for managing <classname>IsisTransaction</classname>s
- within the persistence session.</para>
+ <entry>--connector</entry>
- <para>As mentioned above, when running as a webapp there is
- precisely one <classname>IsisTransaction</classname> per
- session, however when running as a client in client/server mode
- there may be many transactions per session.</para>
- </listitem>
+ <entry>The protocol to use for a client when deploying
+ client/server.</entry>
- <listitem>
- <para><classname>ServicesInjector</classname>, which is
- responsible for injecting domain services into each domain
- object as it is instantiated.</para>
+ <entry><emphasis>encoding-http, encoding-sockets,
+ serializing-sockets, xstream-sockets</emphasis>, or FQCN
+ that implements
+ <classname>ClientConnectionInstaller</classname>.</entry>
- <para>Services are discussed further in <xref
- linkend="sec.DomainServices" />.</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para><classname>PojoAdapterFactory</classname>, which is an
- implementation of the
- <classname>oai.core.metamodel.adapter.ObjectAdapterFactory</classname>
- <acronym>API</acronym>. </para>
+ <entry>Ignored if deployment type is not
+ <emphasis>client</emphasis>. Values are taken from
+ <filename>installer-registry.properties</filename>. See also
+ <xref linkend="sec.ClientConnectorVsViewer" /></entry>
+ </row>
- <para>The default implementation instantiates
- <classname>PojoAdapter</classname> as the corresponding
- implementation of
- <classname>oai.core.metamodel.adapter.ObjectAdapter</classname>.
- There is further coverage of
- <classname>ObjectAdapter</classname>s in <xref
- linkend="sec.ObjectLifecycleManagement" />.</para>
+ <row>
+ <entry>-f <emphasis>fixturename</emphasis></entry>
- <para>In principle this is an extension point; the
- <emphasis>default runtime</emphasis> could be extended to
- provide different implementations of
- <classname>ObjectAdapterFactory</classname>. for example to
- provide more extensive binding support for certain viewers, or
- to provide a fine-grained notifications of changes to underlying
- objects.</para>
- </listitem>
+ <entry>--fixture</entry>
- <listitem>
- <para><classname>ObjectFactory</classname>, which provides
- different implementations for instantiating domain object
- pojos.</para>
+ <entry>Specify fixtures to load (rather than read from
+ configuration file)</entry>
- <para>This is the primary <acronym>API</acronym> that enables
- lazy-loading and automatic tracking of dirty objects.
- Specifically, the <classname>ObjectFactory</classname>
- <acronym>API</acronym> is implemented to allow the bytecode
- implementation to instantiate objects (they provide custom
- subclasses which act as wrappers around the underlying
- object).</para>
+ <entry>FQCN that implements
+ <classname>InstallableFixture</classname>.</entry>
- <para>In addition, the <classname>ClassSubstitutor</classname>
- <acronym>API</acronym> should also be implemented; this allows
- the metamodel to walk the graph ignoring the custom
- subclasses.</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para><classname>OidGenerator</classname>, which provides an
- <acronym>API</acronym> to generate unique
- <classname>Oid</classname>s (object identifiers) for each
- persistent instance.</para>
+ <entry>Ignored if deployment type is not
+ <emphasis>exploration, prototype,
+ server_exploration</emphasis> or
+ <emphasis>server_prototype</emphasis>. If has been
+ specified, any fixtures in the configuration file is
+ ignored.</entry>
+ </row>
- <para>You can think of the <classname>OidGenerator</classname>
- as a generalization of the automatic generation of primary keys
- for entities (using a SQL Server <code>identity</code> keyword
- or Oracle SEQUENCE). However, whereas a primary key id only
- relates to persisted objects, <emphasis>Isis</emphasis>'
- <emphasis>default runtime</emphasis> also allows
- <classname>Oid</classname>s to be created for still-transient
- objects. Because such objects may later be persisted, this
- meanst that the value of the <classname>Oid</classname> can
- change at this point. <emphasis>Isis</emphasis> automatically
- manages this transition.</para>
+ <row>
+ <entry>-c <emphasis>filename</emphasis></entry>
- <para><classname>OidGenerator</classname>s are also required to
- return an <classname>OidStringifier</classname>, which is
- capable of returning a string representation of the
- <classname>Oid</classname>. This capability is exploited by some
- viewers, such as the Restful viewer
- <package>[oai.viewer:restful]</package>, where string
- representations of <classname>Oid</classname>s are required.
- Some <classname>Oid</classname> implementations can choose to
- implement the <classname>DirectlyStringableOid</classname>
- sub-interface, so can be serialized and deserialized into
- strings very directly. Other implementations may rely on the
- fact that all <classname>Oid</classname>s are also
- <classname>oai.core.commons.encoding.Encodable</classname>. The
- string representation for such Oids will however be rather long
- and opaque.</para>
- </listitem>
+ <entry>--config</entry>
- <listitem>
- <para><classname>AdapterManager</classname>, which is
- responsible for tracking the associations between domain object
- pojos, <classname>ObjectAdapter</classname>s and
- <classname>Oid</classname>s.</para>
+ <entry>Loads in the specified configuration file.</entry>
- <para>This, too, is discussed fruther in <xref
- linkend="sec.ObjectLifecycleManagement" />.</para>
- </listitem>
- </itemizedlist>
+ <entry></entry>
- <para>The final scope is for transactions that are created within an
- session.</para>
- </sect2>
+ <entry></entry>
- <sect2 id="sec.TransactionLevelScope">
- <title>Transaction-level scope</title>
+ <entry>The file is loaded in addition to <filename
+ class="directory" moreinfo="none">isis.properties</filename>
+ and the properties files relating to the installed
+ component.</entry>
+ </row>
- <para>The <classname>IsisTransactionManager</classname> (referenced
- by <classname>PersistenceSession</classname>) is responsible for
- creating an <classname>IsisTransaction</classname>. The
- implementation used depends on the
- <classname>PersistenceSession</classname>, but for the more common
- case, object stores, the implementation that is used is
- <classname>ObjectStoreTransaction</classname>. This in turn holds a
- collection of <classname>PersistenceCommand</classname>s which
- represent instructions to add, update or delete objects as required.
- When the transaction is committed, each of these
- <classname>PersistenceCommand</classname>s is executed by the
- configured object store.</para>
+ <row>
+ <entry>-D <emphasis>property=value</emphasis></entry>
- <para>In addition to the commands, the IsisTransaction also holds
- two further sub-components:</para>
+ <entry></entry>
- <itemizedlist>
- <listitem>
- <para>the <classname>UpdateNotifier</classname> is used to
- capture the list of objects that have been added, updated or
- deleted (disposed of). This can be queried by other components
- (such as viewers) as necessary (for example, to know which
- objects to repaint).</para>
+ <entry>Specify additional configuration properties.</entry>
- <para>Once changes are retrieved by client the notifier resets
- its collection so that changes are only available once.</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para>the <classname>MessageBroker</classname> is used to
- capture any messages, warnings, or errors that either the system
- or the domain objects themselves have raised.</para>
+ <entry></entry>
- <para>Domain objects can raise messages using the
- <classname>oai.applib.DomainObjectContainer</classname>,
- automatically injected into all domain objects. The system may
- raise messages if, for example, a concurrency exception
- occurs.</para>
- </listitem>
- </itemizedlist>
+ <entry>Multiple -D flags can be specified.</entry>
+ </row>
- <para>In general it is invalid to access an object from any scope
- once it has been closed. So, for example, the behaviour of the
- <classname>AdapterManager</classname> of a
- <classname>PersistenceSession</classname> is undefined once its
- owning <classname>PersistenceSession</classname> is closed. The
- exception to this rule is the <classname>UpdateNotifier</classname>
- and <classname>MessageBroker</classname>. Other components in the
- framework are free to access these even after the transaction has
- completed, for example in order to repaint the view. See <xref
- linkend="sec.IsisContext" /> for details on how to obtain these
- components and any others.</para>
- </sect2>
- </sect1>
+ <row>
+ <entry>-s</entry>
- <sect1 id="sec.IsisContext">
- <title>Service Locator (<classname>IsisContext</classname>)</title>
+ <entry>--nosplash</entry>
- <para>The <emphasis>default runtime</emphasis> uses the service
- locator pattern to make components (of different scopes) available.
- This is implemented through the <classname>IsisContext</classname>
- class.</para>
+ <entry>Do not show the splash screen</entry>
- <para><classname>IsisContext</classname> itself is abstract; concrete
- subclasses take responsibility for binding the services as
- appropriate. For example, the default implementation for server-side
- deployments is to use the
- <classname>IsisContextThreadLocal</classname>, which (as might be
- expected) binds the <classname>IsisContext</classname> singleton to
- thread-local storage. This is, however, pluggable; the Wicket viewer
- <package>[oai.viewer:wicket]</package> for example provides its own
- implementation <classname>IsisContextForWicket</classname>, which
- binds the IsisContext to an <ulink
- url="http://wicket.apache.org">Apache Wicket</ulink>
- <classname>org.apache.wicket.Session</classname>.</para>
+ <entry></entry>
- <para>As noted above, in general it is invalid to access an object
- from any scope once it has been closed; an
- <classname>IllegalStateException</classname> will be thrown
- otherwise.</para>
- </sect1>
+ <entry></entry>
- <sect1 id="sec.ObjectLifecycleManagement">
- <title>Object Lifecycle Management</title>
+ <entry></entry>
+ </row>
- <para>Managing the lifecycle of domain objects is one of the major
- responsibilities of the <emphasis>default runtime</emphasis>. Most of
- the work goes on in the <classname>PersistenceSession</classname>
- component, discussed earlier in <xref
- linkend="sec.SessionLevelScope" />. In this section we dig a little
- deeper into some of the internals of this component.</para>
+ <row>
+ <entry>-quiet</entry>
- <sect2>
- <title><classname>ObjectAdapter</classname>s and
- <classname>Oid</classname>s</title>
+ <entry></entry>
- <para><emphasis>Apache Isis</emphasis> components do not deal
- directly with domain object pojos; instead they are always wrapped
- by an adapter, call <classname>ObjectAdapter</classname>. This has
- two main responsibilities:</para>
+ <entry>Configure logging to log ERRORs only</entry>
- <itemizedlist>
- <listitem>
- <para>it provides reference to the
- <classname>ObjectSpecification</classname>, which describes the
- structure (properties, collections, actions) of the object's
- type</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para>it provides reference to an <classname>Oid</classname>,
- which is an opaque value that uniquely identifies the object
- instance.</para>
- </listitem>
- </itemizedlist>
+ <entry></entry>
- <para>You can think of <classname>ObjectAdapter</classname> as
- equivalent to <classname>java.lang.Object</classname>, while
- <classname>ObjectSpecification</classname> is in some sense
- equivalent to <classname>java.lang.Class</classname>. The
- <classname>Oid</classname> interface meanwhile is something akin to
- a primary key identifier for an row in a relational database, but it
- is slightly more abstract than that because it can also represent a
- non-persisted object.</para>
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
- <para>It is the <emphasis>metamodel</emphasis> module of
- <emphasis>Isis</emphasis> <package>[oai.core:metamodel]</package>
- defines these interfaces (<classname>ObjectAdapter,
- ObjectSpecifation</classname> and <classname>Oid</classname>), the
- object itself (<classname>ObjectAdapter</classname>), and the
- object's identity (<classname>Oid</classname>). The metamodel itself
- also provides an implementation of
- <classname>ObjectSpecification</classname>.</para>
+ <row>
+ <entry>-verbose</entry>
- <para>The <emphasis>default runtime</emphasis> module
- <package>[oai.runtimes:dflt]</package> provides an implementations
- of the <classname>ObjectAdapter</classname> interface
- (<classname>oai.runtimes.dflt.persistence.adapterfactory.pojo.PojoAdapter</classname>)
- as well as an implementation of the <classname>Oid</classname>
- interface. The actual implementation of <classname>Oid</classname>
- will depend on the object store (persistence) mechanism that the
- runtime has been configured to use.</para>
- </sect2>
+ <entry></entry>
- <sect2>
- <title><classname>AdapterManager</classname></title>
+ <entry>Configure logging to log INFO, WARN and
+ ERRORs.</entry>
- <para>As already mentioned, the <classname>ObjectAdapter</classname>
- maintains a reference to an <classname>Oid</classname> and the
- underlying pojo domain object. To traverse in the other direction -
- that is, from <classname>Oid</classname> to
- <classname>ObjectAdapter</classname> or from pojo to
- <classname>ObjectAdapter</classname> - the default runtime uses its
- internal <classname>AdapterManager</classname> component, which
- maintains two sets of maps. This is shown below:</para>
+ <entry></entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/adapter-manager.png" scale="45" />
- </imageobject>
- </mediaobject>
+ <entry></entry>
- <para>The <classname>AdapterManager</classname> is an example of the
- <ulink
- url="http://martinfowler.com/eaaCatalog/identityMap.html">object-identity
- map pattern</ulink> (as documented more fully in Martin Fowler's
- Patterns of Enterprise Application Architecture). Whenever a domain
- object pojo is handled by the system, and before an adapter for it
- has been created, the runtime checks the
- <classname>AdapterManager</classname> for the instance first, and
- only creates an adapter if the pojo is not mapped. Similarly, if the
- adapter has only an <classname>Oid</classname> value then the
- <classname>AdapterManager</classname> is determine if the object's
- adapter exists.</para>
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
- <para>For value types (such as <classname>String</classname> or
- <classname>java.math.BigDecimal</classname>), things are a little
- different. All values <emphasis>do</emphasis> still have an
- associated <classname>ObjectAdapter</classname>, however the
- <classname>Oid</classname> of these is null, and these objects are
- not stored within the <classname>AdapterManager</classname> maps. A
- value is any object whose <classname>ObjectSpecification</classname>
- has a <classname>ValueFacet</classname> associated with it.
- Typically this is as a result of it have the
- <classname>@Value</classname> annotation; or it might be one of the
- built-in types supported by <emphasis>Isis</emphasis> (such as
- <classname>String</classname>).</para>
- </sect2>
+ <row>
+ <entry>-debug</entry>
- <sect2>
- <title>Aggregate roots and <classname>Oid</classname>
- subtypes</title>
+ <entry></entry>
- <para>Whereas value types have no <classname>Oid</classname>, all
- other domain objects do:</para>
+ <entry>Configure logging to log DEBUG, INFO, WARN and
+ ERRORs.</entry>
- <itemizedlist>
- <listitem>
- <para>Most domain objects that have an
- <classname>Oid</classname> will be domain entities that,
- moreover, are aggregate roots. That is, these are entities that
- are intended to be directly referenced from other entities, and
- have their own, independent identity.</para>
+ <entry></entry>
- <para>For example, a <classname>Customer</classname>,
- <classname>Product</classname> and <classname>Order</classname>
- are all likely to be aggregate root entities.</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para>Lists or sets also have an
- <classname>Oid</classname>.</para>
+ <entry>logging is performed internally using log4j.</entry>
+ </row>
- <para>For example, the <classname>List<Order></classname>
- held internally by a <classname>Customer</classname> to
- represent its list of <classname>Order</classname>s will be
- wrapped in an <classname>ObjectAdapter</classname> and have its
- own <classname>Oid</classname>. Moreover, this
- <classname>ObjectAdapter</classname> will be able to track
- whether the list has been populated from the persistence
- mechanism (so that the collection can be lazily loaded if
- required).</para>
+ <row>
+ <entry>-diagnostics</entry>
- <para>However, such internal lists do not exist outside of their
- owning entity, so these are considered "aggregated" by that
- owning entity. The <classname>Oid</classname> of such objects is
- an instance of type <classname>AggregatedOid</classname>, which
- is basically the <classname>Oid</classname> of its owning entity
- along with an Id for the collection of the object member in
- question (eg "orders").</para>
- </listitem>
+ <entry></entry>
- <listitem>
- <para>Entities can also be aggregated.</para>
+ <entry>print information that can be used to report or
+ diagnose problems</entry>
- <para>If an entity type is annotated with
- <classname>@Aggregated</classname>, then it means that all
- instances of that type are considered as non-root aggregated
- entities, and will also be identified using an
- <classname>AggregatedOid</classname>.</para>
+ <entry></entry>
- <para>For example, <classname>OrderItem</classname> might be
- considered an aggregate type (within its aggregate root,
- <classname>Order</classname>).</para>
- </listitem>
- </itemizedlist>
+ <entry></entry>
- <para>Marking an entity as aggregated may or may not impact how it
- is persisted. For example, an XML or No-SQL (JSON-based) object
- store might conceivably inline the persisted representation of the
- aggregated entity within the document representing the aggregate
- root. An RDBMS-based object store, on the other hand, might choose
- to simply persist every entity in its own table (meaning that the
- distinction between aggregate root entities vs aggregated entities
- is less obvious).</para>
+ <entry></entry>
+ </row>
- <para>For aggregate root entities, the actual
- <classname>Oid</classname> implementation depends upon the
- configured persistence mechanism. For example, if using the XML
- object store then the <classname>SerialOid</classname>
- implementation is used, with the
- <classname>TimeBasedOidGenerator</classname> being used as the
- <classname>OidGenerator</classname> (in other words, creating unique
- instances based on the current time). On the other hand the SQL
- object store happens to have its own <classname>SqlOid</classname>
- implementation, which captures the value generated by the underlying
- relational database.</para>
- </sect2>
+ <row>
+ <entry>-version</entry>
- <sect2 id="sec.DomainServices">
- <title>Domain Services</title>
+ <entry></entry>
- <para>One of the responsibilities of the
- <classname>IsisSystem</classname> is to obtain the list of domain
- services that will be made available to the end-user and which are
- automatically injected into the domain objects.</para>
+ <entry>Print the version of the framework.</entry>
- <para>The default implementation is to load from the
- <filename>isis.properties</filename> file, under the
- <varname>isis.services.prefix</varname> and
- <varname>isis.services</varname> keys:</para>
+ <entry></entry>
- <programlisting>isis.services.prefix = org.apache.isis.example.claims.objstore.dflt
-isis.services = employee.EmployeeRepositoryDefault, claim.ClaimRepositoryDefault</programlisting>
+ <entry></entry>
- <para>For each domain service class, a corresponding domain object
- is instantiated, and then these are held as a simple list within
- IsisSystem.</para>
+ <entry></entry>
+ </row>
- <para>When a <classname>PersistenceSession</classname> is created,
- all domain objects must be mapped with
- <classname>ObjectAdapter</classname>s. Because domain services are
- injected into domain objects, this applies to the domain objects too
- (otherwise the domain objects would appear to hold an unknown
- object).</para>
+ <row>
+ <entry>-h</entry>
- <para>Moreover, it is not valid for persisted domain objects to hold
- references to non-persisted domain objects. We therefore "fool" the
- rest of the framework by automatically creating and mapping
- <classname>ObjectAdapter</classname>s for all the domain services
- objects, with each set to being already persistent. The scope of
- these <classname>ObjectAdapter</classname>s is the same as for any
- other adapter within the <classname>PersistenceSession</classname>;
- only as long as the <classname>PersistenceSession</classname> is
- still open. When the subsequent
- <classname>PersistenceSession</classname> is created,
- <classname>ObjectAdapter</classname>s are created a-new for each
- domain service.</para>
- </sect2>
- </sect1>
- </chapter>
- </part>
+ <entry>--help</entry>
- <part>
- <title>Modules</title>
+ <entry>Print out usage</entry>
- <partintro>
- <para></para>
+ <entry></entry>
- <para></para>
+ <entry></entry>
- <para></para>
- </partintro>
+ <entry>Only the components that can be used are
+ listed.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
- <chapter>
- <title>Runtime Module</title>
+ <para>The --type (deployment type) is discussed in more detail in
+ <xref linkend="sec.DeploymentType" />.</para>
- <para></para>
+ <para>In addition, the <classname>org.apache.isis.Isis</classname>
+ commandline runner has a couple command flags specific to it:</para>
- <para></para>
+ <table>
+ <title><classname>org.apache.isis.Isis</classname> additional
+ command line flags</title>
- <para>The runtime module is the "engine-room" of the framework, taking
- responsibility to manage domain object (pojo) instances at
- runtime.</para>
-
- <para>Each pojo is wrapped in an <classname>ObjectAdapter</classname>
- (cf <classname>java.lang.Object</classname>) from which the
- <classname>ObjectSpecification</classname> (cf
- <classname>java.lang.Class</classname>) can be obtained.</para>
-
- <para>Associated with each <classname>ObjectAdapter</classname> is an
- <classname>Oid</classname>: an opaque serializable identifier to the
- object. The runtime module maintains a 3-way identity map between these,
- allowing forward and reverse lookups.</para>
-
- <para>The runtime module defines a number of APIs the most important of
- which is the <classname>ObjectStore</classname> API. The runtime module
- manages persistence and transaction demarcation, with the actual storage
- of objects being delegated to an object store implementation.</para>
-
- <para>The other major API defined by the runtime module security API,
- dealing with authentication and authorization.</para>
-
- <para>In addition to all the above, the runtime module defines a
- command-line bootstrapper, making it easy to bootstrap Apache Isis from
- a main() or a JUnit test case.</para>
+ <tgroup cols="6">
+ <colspec align="center" />
- <para></para>
+ <colspec colwidth="10%" />
- <sect1>
- <title>Package Layering / Dependencies</title>
+ <colspec />
- <para></para>
+ <colspec />
- <para></para>
+ <colspec />
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/package-dependencies.png"
- scale="60" />
- </imageobject>
- </mediaobject>
+ <colspec />
- <para></para>
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
- <para></para>
+ <entry align="center">Long form</entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <entry align="center">Purpose</entry>
- <para></para>
+ <entry align="center">Typical values</entry>
- <para></para>
+ <entry align="center">Default value</entry>
- <para></para>
- </sect1>
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
- <sect1>
- <title>Runtime, Runner, Installers</title>
+ <tbody>
+ <row>
+ <entry>-u <emphasis>username</emphasis></entry>
- <para></para>
+ <entry>--user</entry>
- <para></para>
+ <entry>Uses the specified name when logging the user in
+ (provided that --password also specified).</entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-1.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <entry></entry>
- <para></para>
+ <entry></entry>
- <para></para>
+ <entry>Ignored if deployment type is not
+ <emphasis>exploration</emphasis>,
+ <emphasis>prototype</emphasis>,
+ <emphasis>server_exploration</emphasis> or
+ <emphasis>server_prototype</emphasis>.</entry>
+ </row>
- <para>The configuration file (<filename class="directory"
- moreinfo="none">isis.properties</filename>) needs to specify what
- resources are used by the application and what fixtures to load. These
- details are common to all the modes that the NOF can be run in.
- Additional properties can be also specified for use in specific modes,
- such as database connection details when using the SQL object
- store.</para>
+ <row>
+ <entry>-p <emphasis>password</emphasis></entry>
- <para>The configuration file <filename class="directory"
- moreinfo="none">isis.properties</filename> is always picked up. In
- addition other properties files will be picked up, if present, based
- on the type, viewer, persistor and connection command line switches
- with the filename matching the option. E.g.</para>
+ <entry>--password</entry>
- <para>-r (or --persistor) hibernate will cause
- <filename>persistor.properties</filename> and <filename
- class="directory"
- moreinfo="none">persistor_hibernate.properties</filename> to be
- used</para>
+ <entry>Specifies password for --username.</entry>
- <para>-t (or --type) client will cause <filename class="directory"
- moreinfo="none">client.properties</filename> to be used</para>
+ <entry></entry>
- <para>-v (or --viewer) dnd will cause
- <filename>viewer.properties</filename> and <filename class="directory"
- moreinfo="none">viewer_dnd.properties</filename> to be used</para>
+ <entry></entry>
- <para>-x (or -- connector) xstream-sockets will cause
- <filename>transport.properties</filename>,
- <filename>transport_sockets.properties</filename>,
- <filename>protocol.properties</filename> and
- <filename>protocol_xstream.properties</filename> to be loaded; because
- of the way that connector is implemented it will also load
- <classname>persistor.properties</classname> and <filename
- class="directory"
- moreinfo="none">persistor_xstream-sockets.properties</filename>
- too.</para>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <para>In addition a particular file can be selected with the -c
- switch. For example</para>
+ <para>The username/password should be valid as per the configured
+ authentication mechanism. For example, if using the file
+ authentication mechanism, then the user/password should reside in the
+ <filename>security_file.password</filename> configuration file.</para>
- <para>-c <filename class="directory"
- moreinfo="none">mysettings.properties</filename></para>
+ <para>The <classname>org.apache.isis.WebServer</classname> webapp
+ runner also has a couple command flags specific to it:</para>
- <para></para>
- </sect1>
+ <table>
+ <title><classname>org.apache.isis.WebRunner</classname> additional
+ command line flags</title>
- <sect1>
- <title>SystemUsingInstallers, and InstallerRegistry</title>
+ <tgroup cols="6">
+ <colspec align="center" />
- <para></para>
+ <colspec colwidth="10%" />
- <para></para>
+ <colspec />
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-2.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <colspec />
- <para></para>
- </sect1>
+ <colspec />
- <sect1>
- <title>Web and Viewers</title>
+ <colspec />
- <para></para>
+ <thead>
+ <row>
+ <entry align="center">Flag</entry>
- <para></para>
+ <entry align="center">Long form</entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-3.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <entry align="center">Purpose</entry>
- <para></para>
- </sect1>
+ <entry align="center">Typical values</entry>
- <sect1>
- <title>Authentication and Authorization</title>
+ <entry align="center">Default value</entry>
- <para></para>
+ <entry align="center">Notes</entry>
+ </row>
+ </thead>
- <para></para>
+ <tbody>
+ <row>
+ <entry>-a <emphasis>address</emphasis></entry>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-4.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <entry>--address</entry>
- <para></para>
+ <entry>Address to listen on</entry>
- <para></para>
+ <entry></entry>
- <para></para>
+ <entry>localhost</entry>
- <sect2>
- <title>Exploration</title>
+ <entry></entry>
+ </row>
- <para>*** this is also mentioned in isis-security.file...</para>
+ <row>
+ <entry>-p <emphasis>portnumber</emphasis></entry>
- <para></para>
+ <entry>--port</entry>
- <para>The list of users that can be switched between during
- exploration can be listed, separated by commas, with the following
- property. If no users are specified the default user "exploration"
- will be used and switching between users will not be
- possible.</para>
+ <entry>Specifies password for --username.</entry>
- <programlisting format="linespecific">isis.exploration.users=sven, dick, bob</programlisting>
+ <entry></entry>
- <para>To disable the showing of exploration menu items set the
- following property to false (by default exploration options are
- shown).</para>
+ <entry>8080</entry>
- <programlisting format="linespecific">isis.exploration.show=false</programlisting>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-w <emphasis>resourseBase</emphasis></entry>
+
+ <entry>--webapp</entry>
+
+ <entry>The location of the webapp relative to
+ <filename>src/main/webapp</filename>.</entry>
+
+ <entry></entry>
+
+ <entry></entry>
+
+ <entry>Usually left at its default, "".</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The --type (deployment type) option influences the defaults for
+ other options, so warrants a little more detail.</para>
+
+ <sect2 id="sec.DeploymentType">
+ <title>Deployment Type</title>
+
+ <para>The deployment type defines the "mode" in which Isis is
+ running. The values correspond to the instances of DeploymentType,
+ and so will always include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>exploration</emphasis></para>
+
+ <para>Exploration mode is for developers to explore and test
+ their code. The framework always uses an in-memory persistor and
+ runs the fixtures at startup to ensure a known state every time
+ the system is started. The user is not prompted to log in, but
+ is automatically logged in as user 'exploration'. The logged in
+ user can be changed on the fly using an option with the user
+ interface; this simply changes the user and does not require an
+ explicit login action. Also, exploration methods defined in the
+ DOM are also available to the user to do things that a user
+ would not normally be allowed to do. These are used expressly
+ for testing the system. Please note it is an error to specify a
+ persistor type in exploration mode.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>prototype</emphasis></para>
+
+ <para>Prototype mode is for demonstrating the system in
+ realistic fashion. The user is always prompted to log in at
+ start up, and can log out and log in again without losing the
+ state of the objects. This allows a user to demonstrate exactly
+ how a system would work.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>single-user</emphasis></para>
+
+ <para>Single user mode runs the system for a single user with
+ object persistence.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>client</emphasis></para>
+
+ <para>Client mode provides multiple users access to a server.
+ With this mode selected the <emphasis>connection</emphasis>
+ option must also be specified.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server-exploration</emphasis></para>
+
+ <para>Server mode, but all clients will automatically be logged
+ in as the 'exploration' user (or using the
+ <classname>LoginFixture</classname> is present, see <xref
+ linkend="sec.LoginFixture" />).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server-prototype</emphasis></para>
+
+ <para>Server mode, but if a <classname>LoginFixture</classname>
+ is present then all clients will automatically be logged in as
+ this user.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>server</emphasis></para>
+
+ <para>Server mode runs Isis as a server for multiple clients.
+ With this mode selected the <emphasis>connection</emphasis>
+ option must also be specified.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If no mode is specified, the framework will start up in
+ <emphasis>prototype</emphasis> mode.</para>
+ </sect2>
+
+ <sect2 id="sec.ClientConnectorVsViewer">
+ <title>Relationship between Client Connectors and Viewers</title>
+
+ <para>You may have noticed that some of the same values can be
+ specified for --viewer and for --connector. Specifically, these
+ common values are: <emphasis>encoding-sockets, encoding-http,
+ serializing-sockets</emphasis>, and
+ <emphasis>xstream-sockets</emphasis>.</para>
+
+ <para>When specified as a client connector using --connector (and
+ provided that the deployment type is client), then Isis is
+ configured to run as a client in a client/server remoting
+ deployment. In this deployment mode there is no persistor/object
+ store configured, instead all requests are sent across the wire to
+ be invoked on a server. The values are used to select an
+ implementation of <classname>ClientConnectionInstaller</classname>
+ which is configured in
+ <filename>installer-registry.properties</filename><footnote>
+ <para>If you look at the source code, you'll see that
+ <classname>ClientConnectionInstaller</classname> is actually a
+ subclass of
+ <classname>PersistenceMechanismInstaller</classname>. So, in
+ fact, there <emphasis>is</emphasis> a persistence mechanism, it
+ just happens to be one that is a proxy to a network connection
+ with a server.</para>
+ </footnote>.</para>
+
+ <para>When these values are specified as a viewer using --viewer
+ (and provided that the deployment type is server), then Isis is
+ configured to run as the corresponding server. The "viewer" in this
+ case is a network listener that receives the requests from the
+ client, unmarshals them, and invokes them on the same domain objects
+ within the server.</para>
+
+ <para>The name of these client connectors/viewers xxx-yyy is a
+ concatenation both the marshalling mechanism (xxx) and underlying
+ transport (yyy):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
+ mechanism (of value types) to serialize/deserialize objects,
+ over TCP/IP sockets.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>encoding-http</emphasis> - Uses the encoding
+ mechanism (of value types) to serialize/deserialize objects,
+ over HTTP.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>serializing-sockets</emphasis> - Uses Java
+ serialization (of value types) to serialize/deserialize objects,
+ over TCP/IP sockets.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>xstream-sockets</emphasis> - Uses the Xstream
+ library to serialize/deserialize objects to/from XML for simple
+ stream communications, over TCP/IP sockets.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>One final remark: the <emphasis>encoding-http</emphasis>
+ viewer can only be run as a webapp; see <xref
+ linkend="sec.WebAppDeployment" /> for more details on how deploying
+ this option.</para>
+ </sect2>
+
+ <sect2 id="sec.LoginFixture">
+ <title>Login Fixtures</title>
<para></para>
+ <para>*** todo</para>
+
<para></para>
</sect2>
</sect1>
<sect1>
- <title>Bytecode Enhancement</title>
+ <title>Configuration Files</title>
<para></para>
<para></para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-5.png"
- scale="80" />
- </imageobject>
- </mediaobject>
-
<para></para>
- <para></para>
+ <para>During start-up Isis loads in a number of configuration files.
+ The main file, <filename class="directory"
+ moreinfo="none">isis.properties</filename>, is always loaded and must
+ be present for the framework to start up. For each of the various
+ types of persistor and viewer, there is a separate configuration file.
+ For example, for the following command line parameters</para>
- <para>The default runtime for <emphasis>Apache Isis</emphasis>
- normally performs lazy loading of references and dirty tracking by
- proxying all domain objects. Two implementations are provided, using
- either cglib or javassist. The application archetype automatically
- configures the use of these proxies. However, some object stores
- (notably, the JPA object store) do not require these proxies (because
- they add their own proxies instead); in which case these can be
- disabled. Alternatively, you may not want to use the bytecode support,
- in which case you can add the appropriate calls for lazy loading and
- dirty tracking.</para>
+ <screen format="linespecific">-v dnd -r xml</screen>
- <para>This area is covered in the {{{./applib/index.html}applib}}, but
- there is also module-specific documentation in the
- {{{./core/bytecode-cglib/index.html}bytecode-cglib}} and
- {{{./core/bytecode-javassist/index.html}bytecode-javassist}}
- modules.</para>
+ <para>specifies that the viewer is to be the drag and drop (<literal
+ moreinfo="none">dnd</literal>) interface, and the persistor is to be
+ the 'xml object store'. As well as loading those components, the
+ framework will look for configuration files named
+ <filename>viewer.properties</filename>, <filename class="directory"
+ moreinfo="none">viewer_dnd.properties</filename>,
+ <filename>persistor.xml</filename> and <filename class="directory"
+ moreinfo="none">persistor_xml.properties</filename> and will load them
+ if found.</para>
<para></para>
</sect1>
+ </chapter>
+
+ <chapter>
+ <title>Standalone Deployment</title>
+
+ <para></para>
+
+ <note>
+ <para>TODO: discuss sealed/signed JARs to prevent tampering?</para>
+ </note>
+
+ <para></para>
<sect1>
- <title></title>
+ <title>Setting up Security</title>
<para></para>
<para></para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-6.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <para></para>
<para></para>
</sect1>
+ </chapter>
- <sect1>
- <title>Fixtures and Services</title>
+ <chapter>
+ <title>Client/Server Deployment</title>
- <para></para>
+ <para></para>
+
+ <para>*** defer encoding-http to next chapter.</para>
+
+ <para></para>
+
+ <section>
+ <title></title>
<para></para>
<para></para>
+ </section>
+ </chapter>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/runtime/architectural-layers-7.png"
- scale="80" />
- </imageobject>
- </mediaobject>
+ <chapter id="sec.WebAppDeployment">
+ <title>Web App Deployment</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title>Setting up Security</title>
<para></para>
<para></para>
<para></para>
+ </sect1>
- <sect2>
- <title>Services</title>
+ <sect1>
+ <title>Running as a WebApp</title>
- <para></para>
+ <para>Isis provides three different ways to run as a webapp:</para>
- <para>The first thing that happens is the logging is set up so that
- everything can be logged. This attempts to load
- <filename>logging.properties</filename> from the
- <filename>config</filename> directory on the filesystem and if that
- cannot be found it will look for the same file in the same directory
- on the classpath. If neither of these are found then a default
- logging configuration will be programmatically installed that writes
- to the console.</para>
-
- <para>Now that logging is initialised the container can prepare for
- bootstrapping the system. The first task is load up all the
- component installers, which is done by the InstallerLookupDefault
- class. This reads the
- <filename>installer-registry.properties</filename> file from
- classpath and attempts to load each class listed. Any class not
- found is logged so it is easy to determine if a component should be
- available. Each installer simply knows how to install a component;
- the component is not loaded at this stage.</para>
-
- <para>Now the container knows what components are available a series
- of option handlers (<classname>OptionHandler</classname>) are
- intialise, with addtional one provided by the Isis container and web
- server subclasses. These interact with the Apache CLI library to
- provide details about the command line parameters and will lookup
- the available components so they can be listed on the command line
- help. With the handlers set up the command line is parsed using the
- Apache library. If this parse fails then the library generates a
- error message with an option summary and displays via the console
- and the startup process terminates.</para>
-
- <para>The last step before bootstrapping starts is to prepare the
- ground for using congfiguration properties. Configuration details
- are loaded by a <classname>ConfigurationBuilder</classname> object
- and will be subsequently placed in an immutable
- <classname>IsisConfiguration</classname> object. Immediately after
- this has been created each handler is visited so that it can, via
- its <methodname>primeConfigurationBuilder</methodname> method, add
- it properties to the builder. This way each command line option is
- converted to one or more properties of the same form as can be
- specified in the properties files, hence we only need one way to
- determine how the system is to be run.</para>
+ <sect2>
+ <title>Using isis.sh</title>
- <para>Now that the ground has been prepared it is time for the
- bootstrapping to begin. This is done via a call to the
- <methodname>bootstrapIsis</methodname> method, which is where the
- process differs for the Isis container and the web server.</para>
+ <screen format="linespecific">$ isis.sh --type server --viewer html --persistor xml
+2007-08-09 12:37:13.671::INFO: Logging to STDERR via org.mortbay.log.StdErrLog
+2007-08-09 12:37:13.801::INFO: jetty-6.0.2
+2007-08-09 12:37:13.954::INFO: Started SocketConnector @ 0.0.0.0:8080
+</screen>
- <para></para>
+ <para>This command runs the Isis with the HTML viewer, allowing
+ multiple clients to access it via a browser. As for the standalone
+ version the users need to access the URL
+ http://<emphasis>server/logon.app</emphasis> to access the log on
+ page.</para>
+ </sect2>
- <para>Services are registered with the Framework at startup via the
- properties file, using the services properties. The
- <methodname>services</methodname> property itself dictates which
- service classes are to be instantiated at startup, for
- example:</para>
+ <sect2>
+ <title>Using WebServer bootstrap</title>
- <programlisting format="linespecific">isis.services = com.mycompany.myapp.dom.BookingFactory,\
- com.mycompany.myapp.dom.CustomerFactoryAndRepository, \
- com.mycompany.myapp.dom.LocationFactoryAndRepository</programlisting>
+ <para>The next mechanism uses the
+ <classname>org.apache.isis.webserver.WebServer</classname> bootstrap
+ to run Isis. This loads up whatever is in the webapp project's
+ <filename>web.xml</filename> file.</para>
- <para>The <methodname>prefix</methodname> property allows you to
- specify the common package once and, hence omit them from the
- classes in the list. The following set of properties is therefore
- equivalent to the previous example:</para>
+ <para><remark>TODO: we don't have a webserver.sh script to show this
+ in action; we probably should.</remark></para>
- <programlisting format="linespecific">isis.services.prefix = com.mycompany.myapp.dom
-isis.services = BookingFactory, CustomerFactoryAndRepository, LocationFactoryAndRepository</programlisting>
[... 2319 lines stripped ...]