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/04/27 00:38:19 UTC
svn commit: r1096936 [2/3] - in /incubator/isis/trunk:
core/progmodel/src/main/java/org/apache/isis/core/progmodel/facets/ignore/
core/runtime/
core/runtime/src/main/java/org/apache/isis/core/runtime/logging/
core/src/docbkx/guide/ runtimes/dflt/ runti...
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=1096936&r1=1096935&r2=1096936&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 Tue Apr 26 22:38:18 2011
@@ -52,182 +52,179 @@
<para><emphasis>Apache Isis</emphasis> is designed to allow programmers
rapidly develop domain-driven applications following the <ulink
url="http://en.wikipedia.org/wiki/Naked_Objects">Naked Objects</ulink>
- pattern. It is made up of a core framework plus a number of alternate
- implementations, and supports various viewers and object stores. Apache
- Isis is hosted at the <ulink url="http://incubator.apache.org/isis">Apache
+ pattern. It is made up of a core framework that supports supports various
+ viewers, along with <acronym>API</acronym>s and implementations relating
+ to security, the programming model, the runtime (persistence) and profile
+ stores (user preferences). <emphasis>Apache Isis</emphasis> is hosted at
+ the <ulink url="http://incubator.apache.org/isis">Apache
Foundation</ulink>, and is licensed under <ulink
url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software
License v2</ulink>.</para>
- <para>This guide is written for ...</para>
- </preface>
+ <para>The role of a runtime is to bootstrap the application and
+ components, and to manage the lifecycle of domain object entities.
+ Typically, this means managing their persistence and identity. In the case
+ of the default runtime, it also means providing support for client/server
+ remoting.</para>
- <!-- main content -->
+ <sect1>
+ <title>Who this Guide is For</title>
- <chapter id="chp.Intro">
- <title>Introduction</title>
+ <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>
+ <listitem>
+ <para>***</para>
- <abstract>
- <para>*** yada yada</para>
- </abstract>
+ <para>This part of the guide ***</para>
+ </listitem>
- <sect1>
- <title>***</title>
+ <listitem>
+ <para>***</para>
- <para><emphasis>*** yada yada</emphasis></para>
+ <para>This part of the guide ***</para>
+ </listitem>
- <para>The guide is divided into *** parts:</para>
+ <listitem>
+ <para>***</para>
- <itemizedlist>
- <listitem>
- <para>*** Introduction</para>
+ <para>This part of the guide ***</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect1>
- <para>This part of the guide discusses the principles and patterns
- of the default runtime.</para>
- </listitem>
+ <sect1>
+ <title>How this Guide relates to other Documentation</title>
- <listitem>
- <para>*** Architecture</para>
+ <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>
+ </sect1>
+ </preface>
- <para>This part of the guide discusses some of the main architecture
- elements of the default runtimes design, distinguishing and
- explaining the reason for the applib, the core modules, the viewers,
- the default implementations of the main APIs exposed by the core,
- and the alternative implementations of those APIs.</para>
- </listitem>
+ <chapter>
+ <title>Core Concepts</title>
- <listitem>
- <para>APIs</para>
+ <para></para>
- <para>This part of the guide goes the (sub-)<acronym>API</acronym>s
- that the runtime exposes</para>
- </listitem>
+ <sect1>
+ <title>IsisContext</title>
- <listitem>
- <para>Default Implementations</para>
+ <para><emphasis>Context</emphasis></para>
- <para>This part of the guide outlines the default implementations of
- the (sub-)<acronym>API</acronym>s.</para>
- </listitem>
+ <para>The ObjectAdapterContext provide access to the main components of
+ the NOF. If the system is started in a multi-user mode then the context
+ will hold specific components for specific execution contexts, allowing
+ the same process to access the same components and different processes
+ to access unique instances.</para>
- <listitem>
- <para>Objectstore Deployments</para>
+ <para>Each execution context will have its own Persistor, Message Broker
+ and Update Notifier.</para>
- <para>This part of the guide describes how to configure the default
- runtime to run with an objectstore.</para>
- </listitem>
+ <para>The Reflector and Configuration are shared among all execution
+ contexts.</para>
- <listitem>
- <para>Client/Server Deployment</para>
+ <para><emphasis>Persistor</emphasis></para>
- <para>This part of the guide describes how to configure the default
- runtime to instead run in client/server mode.</para>
- </listitem>
- </itemizedlist>
+ <para>During startup the persistor is given a set of service objects.
+ During intialisation the persistor must determine the OIDs for these
+ service objects. If the persistor does not know about a service (by its
+ ID) from a previous run then it must generate an OID for the service and
+ persist that with the ID of the service. This allows references to be
+ held persistently to service objects despite the fact that they are
+ singletons.</para>
<para></para>
- <para>***</para>
-
- <para>This guide describes the deployment options that are available
- through using the default implementations of the core module
- <acronym>API</acronym>s, for the most common viewers
- (<acronym>DnD</acronym> and <acronym>HTML</acronym>). Other viewers
- and/or alternative module implementations may require or offer different
- deployment options. For example, the remoting alternative implementation
- requires the bundling up of different client vs server deployments.
- Similarly, a viewer for a mobile phone (there isn't one at the time of
- writing but there could be in the future) would require packaging in a
- certain way.</para>
- </sect1>
- </chapter>
+ <para><emphasis>Identity map</emphasis></para>
- <chapter>
- <title>***</title>
+ <para>Any object that has identity (whether it is persisted or not) must
+ be registered with the identity map. This maps two relationships: domain
+ objects to proxies and OIDs to proxies.</para>
- <abstract>
- <para>*** yada yada</para>
- </abstract>
+ <para>Whenever a domain object is handled by the system, and before a
+ proxy is created, it must be checked against the identity map and if it
+ exists the proxy already in the identity map must be used instead of
+ creating a new proxy.</para>
- <sect1>
- <title>***</title>
+ <para></para>
- <para><emphasis>*** yada yada</emphasis></para>
+ <para></para>
</sect1>
- </chapter>
-
- <part>
- <title>Modules</title>
- <partintro>
- <para></para>
+ <sect1>
+ <title>Bootstrapping using installer-registry.properties</title>
<para></para>
<para></para>
- </partintro>
+ </sect1>
- <chapter>
- <title>Runtime Module</title>
+ <sect1>
+ <title>Scopes</title>
<para></para>
<para></para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/architecture.gif" scale="30" />
+ </imageobject>
+ </mediaobject>
+
<para></para>
+ </sect1>
- <sect1>
- <title>Scopes</title>
+ <sect1>
+ <title>IdentityMap</title>
- <para></para>
+ <para></para>
- <para></para>
+ <para>A persistor should utilise an object-identity map (see Martin
+ Fowler's Patterns of Enterprise Application Architecture) to manage the
+ mapping of domain objects and adapters, and OIDs and adapters. For each
+ domain object the map should store a single adapter, and an OID to that
+ same adapter. The persitor can then guarantee that the same adapter is
+ always provided for a specific domain object or OID</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/architecture.gif" scale="30" />
- </imageobject>
- </mediaobject>
+ <para></para>
+ </sect1>
- <para></para>
- </sect1>
+ <sect1>
+ <title>Profile Stores</title>
- <sect1>
- <title>Bytecode Provider API</title>
+ <para></para>
- <para></para>
+ <para></para>
+ </sect1>
- <para></para>
+ <sect1>
+ <title>Exploration vs Prototype Modes</title>
- <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>
+ <para></para>
- <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></para>
+ </sect1>
+ </chapter>
- <para></para>
- </sect1>
+ <part>
+ <title>Modules</title>
- <sect1>
- <title>Bootstrapping</title>
+ <partintro>
+ <para></para>
- <para></para>
- </sect1>
- </chapter>
+ <para></para>
+
+ <para></para>
+ </partintro>
<chapter>
- <title>Runtime</title>
+ <title>Runtime Module</title>
<para></para>
@@ -262,111 +259,103 @@
<para></para>
<sect1>
- <title>IsisContext</title>
-
- <para><emphasis>Context</emphasis></para>
-
- <para>The ObjectAdapterContext provide access to the main components
- of the NOF. If the system is started in a multi-user mode then the
- context will hold specific components for specific execution contexts,
- allowing the same process to access the same components and different
- processes to access unique instances.</para>
-
- <para>Each execution context will have its own Persistor, Message
- Broker and Update Notifier.</para>
-
- <para>The Reflector and Configuration are shared among all execution
- contexts.</para>
-
- <para><emphasis>Persistor</emphasis></para>
-
- <para>During startup the persistor is given a set of service objects.
- During intialisation the persistor must determine the OIDs for these
- service objects. If the persistor does not know about a service (by
- its ID) from a previous run then it must generate an OID for the
- service and persist that with the ID of the service. This allows
- references to be held persistently to service objects despite the fact
- that they are singletons.</para>
-
- <para><emphasis>Isis</emphasis></para>
+ <title>Bytecode Provider API</title>
<para></para>
- <variablelist>
- <varlistentry>
- <term>Oid</term>
+ <para></para>
- <listitem>
- <para></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>
- <para></para>
- </listitem>
- </varlistentry>
+ <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>
- <varlistentry>
- <term>Resolved State</term>
+ <para></para>
+ </sect1>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
+ <sect1>
+ <title>Bootstrapping</title>
- <varlistentry>
- <term>Version</term>
+ <para></para>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
+ <para></para>
- <varlistentry>
- <term></term>
+ <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>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <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><emphasis>Identity map</emphasis></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>Any object that has identity (whether it is persisted or not)
- must be registered with the identity map. This maps two relationships:
- domain objects to proxies and OIDs to proxies.</para>
-
- <para>Whenever a domain object is handled by the system, and before a
- proxy is created, it must be checked against the identity map and if
- it exists the proxy already in the identity map must be used instead
- of creating a new proxy.</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>
- <para></para>
+ <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>
<para></para>
- </sect1>
-
- <sect1>
- <title>Services Installer</title>
<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>
- <programlisting format="linespecific">isis.services = bom.BookingFactory, bom.CustomerFactoryAndRepository, \
- bom.LocationFactoryAndRepository
-</programlisting>
+ <programlisting format="linespecific">isis.services = com.mycompany.myapp.dom.BookingFactory,\
+ com.mycompany.myapp.dom.CustomerFactoryAndRepository, \
+ com.mycompany.myapp.dom.LocationFactoryAndRepository</programlisting>
<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>
-
- <programlisting format="linespecific">isis.services.prefix = bom
-isis.services = BookingFactory, CustomerFactoryAndRepository, \
- LocationFactoryAndRepository
-</programlisting>
+ to the previous example:</para>
- <para></para>
+ <programlisting format="linespecific">isis.services.prefix = com.mycompany.myapp.dom
+isis.services = BookingFactory, CustomerFactoryAndRepository, LocationFactoryAndRepository</programlisting>
<para></para>
</sect1>
@@ -420,22 +409,6 @@ isis.fixtures = BookingsFixture, Perspec
<para></para>
<sect2>
- <title>Identity Map</title>
-
- <para>A persistor should utilise an object-identity map (see Martin
- Fowler's Patterns of Enterprise Application Architecture) to manage
- the mapping of domain objects and adapters, and OIDs and adapters.
- For each domain object the map should store a single adapter, and an
- OID to that same adapter. The persitor can then guarantee that the
- same adapter is always provided for a specific domain object or
- OID</para>
-
- <para></para>
-
- <para></para>
- </sect2>
-
- <sect2>
<title>Creating Adapters</title>
<para>Numerous methods exist in the persistor (see
@@ -490,433 +463,58 @@ isis.fixtures = BookingsFixture, Perspec
</sect1>
<sect1>
- <title>What makes up a PersistenceSession</title>
+ <title>Configuration Loading</title>
- <para></para>
+ <para>*** explain the principle, how we construct from the "id" of the
+ installer.</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/PersistenceSession.png" scale="30" />
- </imageobject>
- </mediaobject>
+ <para></para>
<para></para>
- </sect1>
- <sect1 id="sec.RuntimeLauncher">
- <title>Launcher</title>
+ <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>
- <para></para>
+ <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>
- <para></para>
+ <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>
- <para>The command line container runs Isis within its own container
- and is best suited to running from the command line where parameters
- are used to determine what components are used and how it all
- runs.</para>
+ <para>-t (or --type) client will cause <filename class="directory"
+ moreinfo="none">client.properties</filename> to be used</para>
- <para>In essense we are running Java with the Isis class like
- this</para>
+ <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>
- <para>$ java -cp <classpath> org.apache.isis.runtime.IsisObject
- <parameters...></para>
+ <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>
- <para>however we typically use a script like the one created by the
- archetype so we can run more easily, eg</para>
+ <para>In addition a particular file can be selected with the -c
+ switch. For example</para>
- <para>$ ./isis.sh <parameters...></para>
-
- <para>The Isis class immediately starts up the logging so that log
- messages are never lost. Next the
- <classname>InstallerLookup</classname> object is instantiated. This
- loads up all the installers that can be found on the classpath, which
- are listed in <filename>installer-registry.properties</filename> . (In
- the source tree, this file physically resides in
- <filename>core/runtime/src/main/resources/</filename>). This allows
- Isis to be aware of all the components that are available, allowing
- names such as xml, file, dnd and html to be used to refer to
- components instead of their fully qualified class names. We maintain
- this list with the framework and public available components will be
- added to the registry list when we know about them.</para>
-
- <para>With these details loaded Isis then parses the command line
- parameters. If there is problem with these then a help text is
- displayed list all the options and the program exits. With the command
- line arguments processed Isis initializes the installers and
- bootstraps the system.</para>
-
- <para></para>
-
- <para></para>
-
- <para></para>
-
- <para></para>
-
- <para>If you are asked from diagnostic information then run Apache
- Isis as follows to capture details about your machine, configuration
- and Isis.</para>
-
- <programlisting>$ isis.sh --diagnostics > diagnostics.txt</programlisting>
-
- <para></para>
-
- <para></para>
-
- <para></para>
-
- <para>A bootstrapper takes care of loading up the Isis framework and
- application, initialising it, and running it. When it starts up it
- reads in a list of components and attempts to load in each one. Any
- component that can be loaded is then available to be used and can then
- be specified on the command line if required. Requesting a component
- that cannot be loaded will result in an error. To resolve such an
- error simply ensure that the component's Jar file is available on the
- class path. All the components supplied with the framework are listed
- in the file <filename class="directory"
- moreinfo="none">installer-registry.properties</filename> which is part
- of the <filename class="directory"
- moreinfo="none">runtime-4.0.jar</filename> file.</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>
-
- <screen format="linespecific">-v dnd -r xml</screen>
-
- <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>
-
- <para></para>
-
- <sect2>
- <title>Class</title>
-
- <para>The bootstrapper is the class
- <classname>org.apache.isis.runtime.Isis</classname> and takes the
- following options on the command line. (Note that in each case there
- is an abbreviated, and a full, version of the option).</para>
-
- <para>There is also an alternative bootstrapper,
- org.apache.isis.webserver.WebServer.</para>
-
- <para></para>
-
- <para>*** can also use org.apache.Isis - just delegates to
- org.apache.isis.runtime.Isis.</para>
-
- <para></para>
- </sect2>
-
- <sect2>
- <title>Configuration</title>
-
- <screen format="linespecific">-c <config file>
---config <config file></screen>
-
- <para>Loads in the specified configuration file, in addition to
- <filename class="directory"
- moreinfo="none">isis.properties</filename> and the properties files
- relating to the installed component.</para>
- </sect2>
-
- <sect2>
- <title>Disable splash</title>
-
- <screen format="linespecific">-s
---nosplash</screen>
-
- <para>Prevents the splash screen from being displayed during start
- up.</para>
- </sect2>
-
- <sect2>
- <title>Help</title>
-
- <screen format="linespecific">-h
---help</screen>
-
- <para>Prints out the options that are available. This is dynamic so
- that only the components that can be used are listed.</para>
- </sect2>
-
- <sect2>
- <title>Logging</title>
-
- <para>The amount of logging detail can be controlled from the
- command line. If no flag is specified only warnings and errors are
- output. All logging level relate to the Log4J levels, which is the
- logging mechanism used by Isis.</para>
-
- <screen format="linespecific">-quiet</screen>
-
- <para>Quiet reduces logging to show errors only.</para>
-
- <screen format="linespecific">-verbose</screen>
-
- <para>Increases logging to show information about the system as it
- runs.</para>
-
- <screen format="linespecific">-debug</screen>
-
- <para>Increases logging to show all logged entries. At this level so
- much is logged that it will likely slow down the system if used when
- outputting log details to the console or other slow devices.</para>
- </sect2>
-
- <sect2>
- <title>Deployment Type (or Mode)</title>
-
- <screen format="linespecific">-t <mode>
---type <mode></screen>
-
- <para>The framework is started up in one of several different
- deployment modes, as listed below:</para>
-
- <para><emphasis>exploration</emphasis> - 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>
-
- <para><emphasis>prototype</emphasis> - 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>
-
- <para><emphasis>single-user</emphasis> - Single user mode runs the
- system for a single user with object persistence.</para>
-
- <para><emphasis>client</emphasis> - Client mode provides multiple
- users access to a server. With this mode selected the
- <emphasis>connection</emphasis> option must also be
- specified.</para>
-
- <para><emphasis>server-exploration</emphasis> - Server mode, but all
- clients will automatically be logged in as the 'exploration' user
- (or as <classname>LoginFixture</classname> is present).</para>
-
- <para><emphasis>server-prototype</emphasis> - Server mode, but if a
- <classname>LoginFixture</classname> is present then all clients will
- automatically be logged in as this user.</para>
-
- <para><emphasis>server</emphasis> - Server mode runs Isis as a
- server for multiple clients. With this mode selected the
- <emphasis>connection</emphasis> option must also be
- specified.</para>
-
- <para>If no mode is specified, the framework will start up in
- <emphasis>prototype</emphasis> mode.</para>
- </sect2>
-
- <sect2>
- <title>Overridden properties</title>
-
- <screen format="linespecific">-D property=value</screen>
-
- <para>Using this flag we can pass in properties from the command
- line that would otherwise need to specified in a configuration file.
- This is normally used to override a property, or to temporarily
- specify one.</para>
- </sect2>
-
- <sect2>
- <title>Password</title>
-
- <screen format="linespecific">-p <password>
---password <password></screen>
-
- <para>Ignored if type is prototype or not used with the user option
- below.</para>
-
- <para>Uses the specified password when logging the user in with the
- username specified with <methodname>--user</methodname>.</para>
- </sect2>
-
- <sect2>
- <title>Persistor</title>
-
- <screen format="linespecific">-r <persistor>
---persistor <persistor></screen>
-
- <para>Ignored if type is client.</para>
-
- <para>The persistor option allows you to choose how the objects
- created by the system will be persisted so they are still available
- the next time you run the system. The following options are
- available with the current distribution, and if none is specified
- then the in-memory persistor will be used for exploration mode and
- xml persistor will be used for other non-client modes by
- default.</para>
-
- <para><emphasis>in-memory</emphasis> - A simple non-persisting
- mechanism that will only hold the persisted object while the virtual
- machine is running. This is used for testing and
- demonstrating.</para>
-
- <para><emphasis>xml</emphasis> - A simple file based mechanism that
- encodes each object's data in an XML file. Alongside the data files
- for the objects are instance lists listing all the files for each
- type of object.<emphasis></emphasis></para>
-
- <para><emphasis><class name></emphasis> - By specifying a
- class name the boot loader will load up that class as the
- persistor.</para>
- </sect2>
-
- <sect2>
- <title>Remote connector</title>
-
- <screen format="linespecific">-x <connector>
---connector <connector></screen>
-
- <para>Ignored if mode is not a client. If the type is a client then
- a connection mechanism can be specified. Connector mechanisms
- available are:-</para>
-
- <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
- mechanism (of value types) to serialize/deserialize objects, over
- TCP/IP sockets.</para>
-
- <para><emphasis>encoding-http</emphasis> - Uses the encoding
- mechanism (of value types) to serialize/deserialize objects, over
- HTTP.</para>
-
- <para><emphasis>serializing-sockets</emphasis> - Uses Java
- serialization (of value types) to serialize/deserialize objects,
- over TCP/IP sockets.</para>
-
- <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>
- </sect2>
-
- <sect2>
- <title>User</title>
-
- <screen format="linespecific">-u <user name>
---user <user name></screen>
-
- <para>Ignored if type is prototype.</para>
-
- <para>Uses the specified name when logging the user in. If the
- password is also specified (see above) then an attempt to log in
- using the supplied user name and password is made; authentication
- failure at this point will exit the program.</para>
- </sect2>
-
- <sect2>
- <title>Viewer</title>
-
- <screen format="linespecific">-v <viewer>
---viewer <viewer></screen>
-
- <para>The viewer option allows you to choose the user interface that
- is used to access your Isis application. The following options are
- available with the current distribution, and if none is specified
- then the drag and drop view will be used by default.</para>
-
- <para><emphasis>dnd</emphasis> - Drag and Drop viewer</para>
-
- <para><emphasis>html</emphasis> - Web browser viewer - accessed via
- standard web browser such as FireFox, Internet Explorer or
- Opera</para>
-
- <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
- mechanism (of value types) to serialize/deserialize objects, over
- TCP/IP sockets.</para>
-
- <para><emphasis>encoding-http</emphasis> - Uses the encoding
- mechanism (of value types) to serialize/deserialize objects, over
- HTTP.</para>
-
- <para><emphasis>serializing-sockets</emphasis> - Uses Java
- serialization (of value types) to serialize/deserialize objects,
- over TCP/IP sockets.</para>
-
- <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>
-
- <para><emphasis><class name></emphasis> - By specifying a
- class name the boot loader will load up that class as the
- viewer</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Configuration Loading</title>
-
- <para>*** explain the principle, how we construct from the "id" of the
- installer.</para>
-
- <para></para>
-
- <para></para>
-
- <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>
-
- <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>
-
- <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>
-
- <para>-t (or --type) client will cause <filename class="directory"
- moreinfo="none">client.properties</filename> to be used</para>
-
- <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>
-
- <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>
-
- <para>In addition a particular file can be selected with the -c
- switch. For example</para>
-
- <para>-c <filename class="directory"
- moreinfo="none">mysettings.properties</filename></para>
+ <para>-c <filename class="directory"
+ moreinfo="none">mysettings.properties</filename></para>
<para></para>
@@ -1109,6 +707,10 @@ isis.fixtures=ExpenseTypes, Employees, E
<sect2>
<title>Users</title>
+ <para>*** this is also mentioned in isis-security.file...</para>
+
+ <para></para>
+
<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"
@@ -1131,7 +733,7 @@ isis.fixtures=ExpenseTypes, Employees, E
</chapter>
<chapter>
- <title></title>
+ <title>Runtime Module</title>
<para></para>
@@ -1139,101 +741,117 @@ isis.fixtures=ExpenseTypes, Employees, E
<para></para>
- <para>There are two startup mechanisms provided with Isis: an Isis
- container; and a web container based on Jetty. Both are run from the
- command line and allow parameters to be specified that control its
- behaviour, determing how logging is performed, what components are
- loaded and so on.</para>
-
- <para>The Isis container is run using the <classname>Isis</classname>
- class from the core-runtime module.</para>
-
- <para>Another way to run Isis is in a independent web container like
- Tomcat or WebSphere. This process is dealt with later.</para>
-
<para></para>
<para></para>
<sect1>
- <title>General process</title>
+ <title>*** Component loggers</title>
- <para>*** this material is probably better in the runtime module ...
- however we should have something here that describes the main concepts
- and classes.</para>
+ <para>*** split this out to the respective modules.</para>
- <para></para>
+ <para>The framework provides a set of component loggers that
+ specifically log the use of a component, adding additional log
+ messages to the Log4j log or write out to a separate file. Additional
+ logger can also be defined for other components. These logger are
+ designed to log the parameters passed to and the the results return
+ from the requests to a component and tend to be more verbose than the
+ general logging just discussed. At present the following components
+ have loggers available:-</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>
+ <itemizedlist>
+ <listitem>
+ <para>The object persistor -
+ <classname>ObjectPersistorLogger</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>The object store -
+ <classname>ObjectStoreLogger</classname></para>
+ </listitem>
+
+ <listitem>
+ <para>The distibution interface -
+ <classname>DistributionLogger</classname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To set up a logger create an instance of it passing in the
+ object you are logging. Then use the logger instance in place of the
+ original component. The constructors for each of the loggers are
+ overloaded so they take a component to decorate and possibly a file
+ name. If the filename is specified then the logging is done to that
+ file. If there is no file name then the events are logged via Log4j.
+ For example the object store persistor would logged by
+ replacing:</para>
+
+ <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
+isis.setObjectPersistor(persistor);</programlisting>
+
+ <para>with this, which will log request to the persistor the <filename
+ class="directory" moreinfo="none">sever-persistor.log</filename>
+ file:</para>
+
+ <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
+persistor = new ObjectManagerLogger(persistor, "server-persistor.log");
+isis.setObjectPersistor(persistor);</programlisting>
+
+ <para>Please note that the log files, when used, are created when the
+ logger is instantiated and will overwrite any exsiting file. This is
+ not normally a problem as we are interested in the activities during
+ an entire session. However on a stateless server where the component
+ is being recreated each time the continual recreation of the file
+ could be a problem.</para>
+
+ <sect2>
+ <title>Defining a logger</title>
- <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>To define a logger extend the Logger class, providing a
+ suitable constructor, and implement the
+ <methodname>getDecoratedClass</methodname> so it passes back the
+ <classname>Class</classname> object of the class being decorated
+ (this allows the Log4j logger to log messages as that class rather
+ than as a separate class). Within the subclass you can use the
+ following methods:</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>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis> <methodname>void log(String
+ message)</methodname> </emphasis></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>
+ <para>output a log entry with the specified message.</para>
+ </listitem>
- <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>
+ <listitem>
+ <para><emphasis> <methodname>void log(String message, Object
+ result)</methodname> </emphasis></para>
- <para></para>
+ <para>output a log entry with the specified message and the
+ specified result. This is useful when needing to show both the
+ entry and exit states, or the paramters and the return
+ value.</para>
+ </listitem>
- <para></para>
- </sect1>
- </chapter>
+ <listitem>
+ <para><emphasis> <methodname>void close()</methodname>
+ </emphasis></para>
- <chapter id="chp.ObjectStoreApi">
- <title>Object Store API</title>
+ <para>closes the file that is being written to.</para>
+ </listitem>
+ </itemizedlist>
- <abstract>
- <para>***</para>
- </abstract>
+ <para></para>
- <sect1>
- <title></title>
+ <para></para>
- <para></para>
+ <para></para>
- <para></para>
+ <para></para>
+ </sect2>
+ </sect1>
- <note>
- <para>TODO: tidy up the following paras, were just copied/pasted in
- from APT</para>
- </note>
+ <sect1>
+ <title>Bytecode Enhancement API</title>
<para></para>
@@ -1252,40 +870,43 @@ isis.fixtures=ExpenseTypes, Employees, E
</sect1>
<sect1>
- <title>Alternative Implementations</title>
+ <title>Persistor API</title>
<para></para>
</sect1>
<sect1>
- <title>Writing your own Object Store</title>
+ <title>Object Store API</title>
<para></para>
- <para>When a object is persisted the object store's
- <methodname>createCreateObjectCommand</methodname> method is called.
- This create a command object (see GoF Patterns books), which will
- later be processed when the transaction is be commited. All
- persistence actions (create, destroy and save) are collected together
- until this point. This way when a transaction is aborted all commands
- can be thrown away without recourse to the database. Specifically it
- is the <methodname>execute</methodname> method that is called on the
- command, and this command runs an insert command agains the the
- database.</para>
-
<para></para>
- </sect1>
- </chapter>
- <chapter id="chp.ProfileStoreApi">
- <title>Profile Store API and Implementations</title>
+ <sect2>
+ <title>Writing your own Object Store</title>
+
+ <para>*** do we want to include this section ... it'll be somewhat
+ long!</para>
- <abstract>
- <para>***</para>
- </abstract>
+ <para></para>
+
+ <para>When a object is persisted the object store's
+ <methodname>createCreateObjectCommand</methodname> method is called.
+ This create a command object (see GoF Patterns books), which will
+ later be processed when the transaction is be commited. All
+ persistence actions (create, destroy and save) are collected
+ together until this point. This way when a transaction is aborted
+ all commands can be thrown away without recourse to the database.
+ Specifically it is the <methodname>execute</methodname> method that
+ is called on the command, and this command runs an insert command
+ agains the the database.</para>
+
+ <para></para>
+ </sect2>
+ </sect1>
<sect1>
- <title></title>
+ <title>Profile Store API</title>
<para></para>
@@ -1322,561 +943,609 @@ isis.fixtures=ExpenseTypes, Employees, E
<para></para>
- <note>
- <para>TODO: tidy up the following paras, were just copied/pasted in
- from APT</para>
- </note>
+ <para></para>
+
+ <para>To store profiles (during exploration) for users the a profile
+ store must be specified.</para>
+
+ <para>On the command line use -e xml to store them in an XML.</para>
+
+ <para>Without this the profile will simply be kept in memory, and lost
+ on exit.</para>
<para></para>
- <para>***</para>
+ <sect2>
+ <title>Setting up Perspectives (Profile Fixtures)</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para>Perspectives allow the set of services available to a user (eg
+ as icons in the DnD viewer) to be customized for that user. Since
+ these services represent the "start points" for the user to interact
+ with the domain model, they in a sense define an application on a
+ per-user basis.</para>
+
+ <para>The perspectives are stored in user-profiles, which are a
+ persistence mechanism independent of the object store. (The intent
+ is for user profiles to store additional information for use by
+ viewers, for example allowing a user to reskin an application or
+ change colors or fonts. As of NOF 4.0 the functionality provided is
+ still limited, however).</para>
+
+ <para>The key here is that if a user logs in and no perspective
+ exists for that user then one will be created for them. The new
+ perspective will be a copy of the 'template' perspective, or, if
+ none was defined, a perspective containing all the known services.
+ To create a template perspective add a perspective fixture that
+ calls <methodname>saveAsDefault()</methodname>, rather than
+ <methodname>saveForUser()</methodname> for a named user, as shown
+ below.</para>
+
+ <programlisting>public class PerspectivesFixture extends UserProfileFixture {
+ @Override
+ protected void installProfiles() {
+ Profile profile = newUserProfile();
+ Perspective perspective = profile.newPerspective("ECS");
+ perspective.addToServices(LocationFactory.class);
+ perspective.addToServices(CustomerRepository.class);
+ perspective.addToServices(PaymentMethodFactory.class);
+
+ saveAsDefault(profile);
+ }
+}
+</programlisting>
+
+ <para>With that set up, when a new user now logs in they will see
+ three service icons on the screen for locations, customers and
+ payment methods. On the drag and drop user interface the user can
+ add and remove services from their perspective. To remove a service
+ icon right-click on the grey border and select the close option. To
+ add a service select the Services... option from the application
+ menu (accessed by right-clicking on the application background) and
+ drag the required service onto the desktop. Unfortunately there is
+ no similar mechanism available on the HTML user interface so you
+ will need to modify the created perspectives via the DND UI.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Webapp Module</title>
+
+ <para></para>
+
+ <para>The webapp module is a small module that provides reusable servlet
+ context listeners and filters to webapp viewers. They include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>IsisWebAppBootstrapper</classname> which is a
+ servlet context listener to bootstrap an Isis runtime and bind to
+ the servlet context</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>IsisSessionFilter</classname> which is a filter
+ used to creating an IsisSession for each request (the Open session
+ in View pattern)</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>ResourceServlet</classname> which serves up static
+ content from the specified resource</para>
+ </listitem>
+
+ <listitem>
+ <para><classname>StaticContentFilter</classname> which decorates
+ static content with headers for caching</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><note>
+ <para>The <classname>ResourceServlet</classname> and
+ <classname>StaticContentFilter</classname> will likely move back to
+ core framework because they are likely to be of use to most runtime
+ implementations.</para>
+ </note></para>
+
+ <para>Not every webapp-based viewer is required to use these classes;
+ refer to their documentation for exact details of what should reside in
+ the web.xml.</para>
+
+ <para></para>
+ </chapter>
+
+ <chapter>
+ <title>Webserver Module</title>
+
+ <para></para>
+
+ <para>The webserver module is intended to make it easy to run
+ webapp-based viewers, using the webapp as defined in
+ <filename>src/main/webapp/WEB-INF/web.xml</filename>.</para>
+
+ <para>This is a useful facility to have during development, but is not
+ (expected to be) needed for deployment. In essence all the module does
+ is to bundle up Jetty.</para>
+
+ <para>An alternative would be to use <code>mvn jetty:run</code>; this
+ module is for when you'd rather just run a standalone program (ie, with
+ a <methodname>main()</methodname> in it) without the overhead of
+ <emphasis>Maven</emphasis>.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>There is also an alternative bootstrapper,
+ org.apache.isis.webserver.WebServer.</para>
+
+ <para></para>
+
+ <para></para>
+
+ <sect1>
+ <title></title>
+
+ <para></para>
+
+ <sect2>
+ <title>Properties</title>
+
+ <para>The embedded web server (implemented by Jetty) has only one
+ properties</para>
+
+ <programlisting format="linespecific">isis.embedded-web-server.port=8080</programlisting>
+
+ <para>Which specifies the port to use when prototyping.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Remoting Modules</title>
+
+ <para></para>
+
+ <para></para>
+
+ <para></para>
+
+ <para>There are two startup mechanisms provided with Isis: an Isis
+ container; and a web container based on Jetty. Both are run from the
+ command line and allow parameters to be specified that control its
+ behaviour, determing how logging is performed, what components are
+ loaded and so on.</para>
+
+ <para>The Isis container is run using the <classname>Isis</classname>
+ class from the core-runtime module.</para>
+
+ <para>Another way to run Isis is in a independent web container like
+ Tomcat or WebSphere. This process is dealt with later.</para>
+
+ <para></para>
+
+ <para></para>
+ </chapter>
+ </part>
+
+ <part>
+ <title>Runtime APIs</title>
- <para></para>
- </sect1>
+ <chapter>
+ <title>Bytecode Enhancement API</title>
- <sect1>
- <title>Alternative Implementations</title>
+ <para></para>
- <para></para>
+ <para></para>
+ </chapter>
- <para></para>
+ <chapter id="chp.ObjectStoreApi">
+ <title>Persistor API and Object Store API</title>
- <para></para>
- </sect1>
+ <abstract>
+ <para>***</para>
+ </abstract>
<sect1>
<title></title>
<para></para>
- <para>To store profiles (during exploration) for users the a profile
- store must be specified.</para>
-
- <para>On the command line use -e xml to store them in an XML.</para>
+ <para></para>
- <para>Without this the profile will simply be kept in memory, and lost
- on exit.</para>
+ <note>
+ <para>TODO: tidy up the following paras, were just copied/pasted in
+ from APT</para>
+ </note>
<para></para>
</sect1>
</chapter>
+ </part>
- <chapter>
- <title>Runtime Module</title>
+ <part>
+ <title>Deployment</title>
- <para></para>
+ <chapter>
+ <title>Running in Development</title>
- <para></para>
+ <para>*** ie, not deployed, just running immediately.</para>
<para></para>
<para></para>
- <para></para>
+ <sect1 id="sec.RuntimeLauncher">
+ <title>Bootstrapping (Isis launcher)</title>
- <sect1>
- <title>Component loggers</title>
+ <para></para>
- <para>The NOF provides a set of component loggers that specifically
- log the use of a component, adding additional log messages to the
- Log4j log or write out to a separate file. Additional logger can also
- be defined for other components. These logger are designed to log the
- parameters passed to and the the results return from the requests to a
- component and tend to be more verbose than the general logging just
- discussed. At present the following components have loggers
- available:-</para>
+ <para></para>
- <itemizedlist>
- <listitem>
- <para>The object persistor -
- <classname>ObjectPersistorLogger</classname></para>
- </listitem>
+ <para>The command line container runs Isis within its own container
+ and is best suited to running from the command line where parameters
+ are used to determine what components are used and how it all
+ runs.</para>
- <listitem>
- <para>The object store -
- <classname>ObjectStoreLogger</classname></para>
- </listitem>
+ <para>In essense we are running Java with the Isis class like
+ this:</para>
- <listitem>
- <para>The distibution interface -
- <classname>DistributionLogger</classname></para>
- </listitem>
- </itemizedlist>
+ <para>$ java -cp <classpath>
+ org.apache.isis.runtimes.dflt.runtime.Isis
+ <parameters...></para>
- <para>To set up a logger create an instance of it passing in the
- object you are logging. Then use the logger instance in place of the
- original component. The constructors for each of the loggers are
- overloaded so they take a component to decorate and possibly a file
- name. If the filename is specified then the logging is done to that
- file. If there is no file name then the events are logged via Log4j.
- For example the object store persistor would logged by
- replacing:</para>
+ <para>however we typically use a script like the one created by the
+ archetype so we can run more easily, eg</para>
- <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
-isis.setObjectPersistor(persistor);</programlisting>
+ <para>$ ./isis.sh <parameters...></para>
- <para>with this, which will log request to the persistor the <filename
- class="directory" moreinfo="none">sever-persistor.log</filename>
- file:</para>
+ <para>The Isis class immediately starts up the logging so that log
+ messages are never lost. Next the
+ <classname>InstallerLookup</classname> object is instantiated. This
+ loads up all the installers that can be found on the classpath, which
+ are listed in <filename>installer-registry.properties</filename> . (In
+ the source tree, this file physically resides in
+ <filename>core/runtime/src/main/resources/</filename>). This allows
+ Isis to be aware of all the components that are available, allowing
+ names such as xml, file, dnd and html to be used to refer to
+ components instead of their fully qualified class names. We maintain
+ this list with the framework and public available components will be
+ added to the registry list when we know about them.</para>
- <programlisting format="linespecific">ObjectAdapterPersistor persistor = new ObjectStorePersistor();
-persistor = new ObjectManagerLogger(persistor, "server-persistor.log");
-isis.setObjectPersistor(persistor);</programlisting>
+ <para>With these details loaded Isis then parses the command line
+ parameters. If there is problem with these then a help text is
+ displayed list all the options and the program exits. With the command
+ line arguments processed Isis initializes the installers and
+ bootstraps the system.</para>
- <para>Please note that the log files, when used, are created when the
- logger is instantiated and will overwrite any exsiting file. This is
- not normally a problem as we are interested in the activities during
- an entire session. However on a stateless server where the component
- is being recreated each time the continual recreation of the file
- could be a problem.</para>
+ <para></para>
- <sect2>
- <title>Defining a logger</title>
+ <para></para>
- <para>To define a logger extend the Logger class, providing a
- suitable constructor, and implement the
- <methodname>getDecoratedClass</methodname> so it passes back the
- <classname>Class</classname> object of the class being decorated
- (this allows the Log4j logger to log messages as that class rather
- than as a separate class). Within the subclass you can use the
- following methods:</para>
+ <para></para>
- <itemizedlist>
- <listitem>
- <para><emphasis> <methodname>void log(String
- message)</methodname> </emphasis></para>
+ <para></para>
- <para>output a log entry with the specified message.</para>
- </listitem>
+ <para>If you are asked from diagnostic information then run Apache
+ Isis as follows to capture details about your machine, configuration
+ and Isis.</para>
- <listitem>
- <para><emphasis> <methodname>void log(String message, Object
- result)</methodname> </emphasis></para>
+ <programlisting>$ isis.sh --diagnostics > diagnostics.txt</programlisting>
- <para>output a log entry with the specified message and the
- specified result. This is useful when needing to show both the
- entry and exit states, or the paramters and the return
- value.</para>
- </listitem>
+ <para></para>
- <listitem>
- <para><emphasis> <methodname>void close()</methodname>
- </emphasis></para>
+ <para></para>
- <para>closes the file that is being written to.</para>
- </listitem>
- </itemizedlist>
+ <para></para>
- <para></para>
+ <para>A bootstrapper takes care of loading up the Isis framework and
+ application, initialising it, and running it. When it starts up it
+ reads in a list of components and attempts to load in each one. Any
+ component that can be loaded is then available to be used and can then
+ be specified on the command line if required. Requesting a component
+ that cannot be loaded will result in an error. To resolve such an
+ error simply ensure that the component's Jar file is available on the
+ class path. All the components supplied with the framework are listed
+ in the file <filename class="directory"
+ moreinfo="none">installer-registry.properties</filename> which is part
+ of the JAR file for <package>[oai.runtimes.dflt:runtime]</package>
+ module.</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></para>
+ <screen format="linespecific">-v dnd -r xml</screen>
- <para></para>
- </sect2>
- </sect1>
+ <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>
- <sect1>
- <title>Diagnostics (Logging)</title>
+ <para></para>
<para></para>
<sect2>
- <title>Snapshot appenders</title>
-
- <para>The NOF provides a number of appenders that create a snapshot
- of the recently logged events instead of capturing all events since
- the system started. The benefits here are twofold. First, writing to
- the appenders is minimised as they are only written when errors
- occur or the user demands it. Second, the partial log can be
- automatically sent over the network to someone who needs to know
- when things have gone wrong.</para>
-
- <para>All the snapshot appends support the same basic
- properties:-</para>
+ <title>Class</title>
- <itemizedlist>
- <listitem>
- <para><emphasis> <methodname>addInfo</methodname>
- </emphasis></para>
+ <para>The bootstrapper is the class
+ <classname>org.apache.isis.runtime.Isis</classname> and takes the
+ following options on the command line. (Note that in each case there
+ is an abbreviated, and a full, version of the option).</para>
- <para>(boolean) indicates whether to prepend details about the
- machine, os and Java to log, eg</para>
+ <para></para>
- <programlisting format="linespecific">Snapshot:- Thu Dec 01 14:34:24 GMT 2005
- R Matthews
- Windows XP (x86) 5.1
- Java HotSpot(TM) Client VM 1.4.2_04-b05
- Version 000000</programlisting>
- </listitem>
+ <para></para>
- <listitem>
- <para><emphasis> <methodname>bufferSize</methodname>
- </emphasis></para>
+ <para>*** can also use org.apache.Isis - just delegates to
+ org.apache.isis.runtime.Isis.</para>
- <para>(integer) the number of events to write out to the
- snapshot. Defaults to 512 events.</para>
- </listitem>
+ <para></para>
+ </sect2>
- <listitem>
- <para><emphasis> <methodname>locationInfo</methodname>
- </emphasis></para>
+ <sect2>
+ <title>Configuration</title>
- <para>(boolean) whether to capture the details of where in the
- code the event was generated. Note - capturing this information
- can be quite expensive.</para>
- </listitem>
+ <screen format="linespecific">-c <config file>
+--config <config file></screen>
- <listitem>
- <para><emphasis> <methodname>evaluatorClass</methodname>
- </emphasis></para>
+ <para>Loads in the specified configuration file, in addition to
+ <filename class="directory"
+ moreinfo="none">isis.properties</filename> and the properties files
+ relating to the installed component.</para>
+ </sect2>
- <para>(<classname>org.apache.log4j.spi.TriggeringEventEvaluator</classname>)
- a trigger that determines when a snapshot should be created. The
- trigger object is given each event that is logged and flags when
- to produce a snapsho.</para>
-
- <para>When not trigger is specified a default trigger is applied
- that triggers a snapshot when an event of level ERROR or FATAL
- occurs.</para>
- </listitem>
- </itemizedlist>
+ <sect2>
+ <title>Disable splash</title>
- <sect3>
- <title>File snapshot appender</title>
+ <screen format="linespecific">-s
+--nosplash</screen>
- <para>The <classname>FileSnapshotAppender</classname> writes the
- snapshot to timestamped file. The following properties can be
- specified:-</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis><methodname>directory</methodname></emphasis></para>
-
- <para>The directory path where the files are to be created. If
- none is specified then the working directory will be
- used.</para>
- </listitem>
-
- <listitem>
- <para><emphasis><methodname>extension</methodname></emphasis></para>
-
- <para>The extension type to append to the file name.</para>
- </listitem>
-
- <listitem>
- <para><emphasis><methodname>fileName</methodname></emphasis></para>
-
- <para>The base name of the log file, which will have timestamp
- appended. Defaults to 'log-snapshot-'.</para>
- </listitem>
- </itemizedlist>
-
- <para>The following example writes xml snapshots to the logs
- directory to files ending with '.xml'.</para>
-
- <programlisting format="linespecific">log4j.appender.Snapshot=org.apache.isis.utility.logging.FileSnapshotAppender
-log4j.appender.Snapshot.bufferSize=1024
-log4j.appender.Snapshot.addInfo=true
-log4j.appender.Snapshot.locationInfo=true
-log4j.appender.Snapshot.directory=logs
-log4j.appender.Snapshot.extension=xml
-log4j.appender.Snapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>
- </sect3>
-
- <sect3>
- <title>Popup snapshot appender</title>
-
- <para>The <classname>PopupSnapshotAppender</classname> displays a
- popup dialog showing the snapshot.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata align="left" fileref="images/popup-snapshot.png"
- format="PNG" width="12.5cm" />
- </imageobject>
- </mediaobject>
-
- <para>Do not use this on a server as there will be no one sitting
- in front of it to see it. It has no properties so its
- configuration is short.</para>
-
- <programlisting format="linespecific">log4j.appender.Popup=org.apache.isis.utility.logging.PopupSnapshotAppender
-log4j.appender.Popup.layout=org.apache.log4j.PatternLayout
-log4j.appender.Popup.layout.ConversionPattern=%-5r [%-20c{1} %-10t %-5p] %m%n
-</programlisting>
- </sect3>
+ <para>Prevents the splash screen from being displayed during start
+ up.</para>
+ </sect2>
- <sect3>
- <title>Email snapshot appender</title>
+ <sect2>
+ <title>Help</title>
- <para>The <classname>SmtpSnapshotAppender</classname> generates an
- email with the snapshot in it and sends it to a specified
- recipient. The following properties can be specified:-</para>
+ <screen format="linespecific">-h
+--help</screen>
- <itemizedlist>
- <listitem>
- <para><emphasis><methodname>server</methodname></emphasis></para>
+ <para>Prints out the options that are available. This is dynamic so
+ that only the components that can be used are listed.</para>
+ </sect2>
- <para>Address of the email server</para>
- </listitem>
+ <sect2>
+ <title>Logging</title>
- <listitem>
- <para><emphasis><methodname>port</methodname></emphasis></para>
+ <para>The amount of logging detail can be controlled from the
+ command line. If no flag is specified only warnings and errors are
+ output. All logging level relate to the Log4J levels, which is the
+ logging mechanism used by Isis.</para>
- <para>The port the server listen on for SMTP requests.
- Defaults to port 25.</para>
- </listitem>
+ <screen format="linespecific">-quiet</screen>
- <listitem>
- <para><emphasis><methodname>recipient</methodname></emphasis></para>
+ <para>Quiet reduces logging to show errors only.</para>
- <para>Email address to send the snapshot to.</para>
- </listitem>
+ <screen format="linespecific">-verbose</screen>
- <listitem>
- <para><emphasis><methodname>domain</methodname></emphasis></para>
+ <para>Increases logging to show information about the system as it
+ runs.</para>
- <para>The address that client connects to the server with.
- Some email servers validate the sender's address in the MAIL
- FROM command so you may need to specify a real address
- here.</para>
- </listitem>
- </itemizedlist>
+ <screen format="linespecific">-debug</screen>
- <para>The following example sends a short HTML snapshot logs to
- logs@support.acme.com, via the email server at my.emailserver.com
- using port 25.</para>
+ <para>Increases logging to show all logged entries. At this level so
+ much is logged that it will likely slow down the system if used when
+ outputting log details to the console or other slow devices.</para>
+ </sect2>
- <programlisting format="linespecific">log4j.appender.EmailSnapshot=org.apache.isis.utility.logging.SmtpSnapshotAppender
-log4j.appender.EmailSnapshot.bufferSize=50
-log4j.appender.EmailSnapshot.addInfo=true
-log4j.appender.EmailSnapshot.server=my.emailserver.com
-log4j.appender.EmailSnapshot.port=25
-log4j.appender.EmailSnapshot.recipient=logs@support.acme.com
-log4j.appender.EmailSnapshot.layout=org.apache.log4j.HTMLLayout</programlisting>
- </sect3>
+ <sect2>
+ <title>Deployment Type (or Mode)</title>
- <sect3>
- <title>Socket snapshot appender</title>
+ <screen format="linespecific">-t <mode>
+--type <mode></screen>
- <para>The <classname>SocketSnapshotAppender</classname>
- establishes a socket connection to a server and passes across the
- the snapshot. This is designed to be used with
- <classname>SnapshotServer</classname>, which collects collects
- snapshots from multiple clients.</para>
+ <para>The framework is started up in one of several different
+ deployment modes, as listed below:</para>
- <para>The following example sends an XML snapshot to a server on a
- private network.</para>
+ <para><emphasis>exploration</emphasis> - 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>
- <programlisting format="linespecific">log4j.appender.SocketSnapshot=org.apache.isis.utility.logging.SocketSnapshotAppender
-log4j.appender.SocketSnapshot.bufferSize=1024
-log4j.appender.SocketSnapshot.addInfo=true
-log4j.appender.SocketSnapshot.server=191.168.1.1
-log4j.appender.SocketSnapshot.port=12345
-log4j.appender.SocketSnapshot.layout=org.apache.log4j.xml.XMLLayout</programlisting>
+ <para><emphasis>prototype</emphasis> - 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>
- <para>The snaphot server should be directed to a maching running
- the server. The server is run using the following command:</para>
+ <para><emphasis>single-user</emphasis> - Single user mode runs the
+ system for a single user with object persistence.</para>
- <screen format="linespecific">java -cp isis.jar org.apache.isis.utility.logging.SnapshotServer</screen>
+ <para><emphasis>client</emphasis> - Client mode provides multiple
+ users access to a server. With this mode selected the
+ <emphasis>connection</emphasis> option must also be
+ specified.</para>
- <para></para>
+ <para><emphasis>server-exploration</emphasis> - Server mode, but all
+ clients will automatically be logged in as the 'exploration' user
+ (or as <classname>LoginFixture</classname> is present).</para>
- <para>The server needs a properties file with the following
- properties defined (with the prefix
- <methodname>isis.snapshotserver.</methodname>):-</para>
+ <para><emphasis>server-prototype</emphasis> - Server mode, but if a
+ <classname>LoginFixture</classname> is present then all clients will
+ automatically be logged in as this user.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis><methodname>server</methodname></emphasis></para>
+ <para><emphasis>server</emphasis> - Server mode runs Isis as a
+ server for multiple clients. With this mode selected the
+ <emphasis>connection</emphasis> option must also be
+ specified.</para>
- <para>Address of the server.</para>
- </listitem>
+ <para>If no mode is specified, the framework will start up in
+ <emphasis>prototype</emphasis> mode.</para>
+ </sect2>
- <listitem>
- <para><emphasis><methodname>port</methodname></emphasis></para>
+ <sect2>
+ <title>Overridden properties</title>
- <para>The port the server listens on for logging requests.
- Defaults to port 9289.</para>
- </listitem>
+ <screen format="linespecific">-D property=value</screen>
- <listitem>
- <para><emphasis><methodname>directory</methodname></emphasis></para>
+ <para>Using this flag we can pass in properties from the command
+ line that would otherwise need to specified in a configuration file.
+ This is normally used to override a property, or to temporarily
+ specify one.</para>
+ </sect2>
- <para>The directory path where the transferred files are to be
- saved. If none is specified then the working directory will be
- used.</para>
- </listitem>
+ <sect2>
+ <title>Password</title>
- <listitem>
- <para><emphasis><methodname>fileName</methodname></emphasis></para>
+ <screen format="linespecific">-p <password>
+--password <password></screen>
- <para>The base name of the log file, which will have timestamp
- appended. Defaults to 'log-snapshot-'.</para>
- </listitem>
+ <para>Ignored if type is prototype or not used with the user option
+ below.</para>
- <listitem>
- <para><emphasis><methodname>extension</methodname></emphasis></para>
+ <para>Uses the specified password when logging the user in with the
+ username specified with <methodname>--user</methodname>.</para>
+ </sect2>
- <para>The extension type to append to the file name.</para>
- </listitem>
- </itemizedlist>
+ <sect2>
+ <title>Persistor</title>
- <para>An example configuration would be:-</para>
+ <screen format="linespecific">-r <persistor>
+--persistor <persistor></screen>
- <programlisting format="linespecific">isis.snapshotserver.port=12345
-isis.snapshotserver.directory=logs
-isis.snapshotserver.filename=log
-isis.snapshotserver.extension=xml</programlisting>
- </sect3>
+ <para>Ignored if type is client.</para>
- <sect3>
- <title>Web snapshot appender</title>
+ <para>The persistor option allows you to choose how the objects
+ created by the system will be persisted so they are still available
+ the next time you run the system. The following options are
+ available with the current distribution, and if none is specified
+ then the in-memory persistor will be used for exploration mode and
+ xml persistor will be used for other non-client modes by
+ default.</para>
- <para>The <classname>WebSnapshotAppender</classname> sends the
- snapshot to a web server. The following properties can be
- specified:-</para>
+ <para><emphasis>in-memory</emphasis> - A simple non-persisting
+ mechanism that will only hold the persisted object while the virtual
+ machine is running. This is used for testing and
+ demonstrating.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis><methodname>url</methodname></emphasis></para>
+ <para><emphasis>xml</emphasis> - A simple file based mechanism that
+ encodes each object's data in an XML file. Alongside the data files
+ for the objects are instance lists listing all the files for each
+ type of object.<emphasis></emphasis></para>
- <para>URL of server to post data to (including the protocol
- 'http').</para>
- </listitem>
+ <para><emphasis><class name></emphasis> - By specifying a
+ class name the boot loader will load up that class as the
+ persistor.</para>
+ </sect2>
- <listitem>
- <para><emphasis><methodname>proxyAddress</methodname></emphasis></para>
+ <sect2>
+ <title>Remote connector</title>
- <para>Address of web proxy if one is being used.</para>
- </listitem>
+ <screen format="linespecific">-x <connector>
+--connector <connector></screen>
- <listitem>
- <para><emphasis><methodname>proxyPort</methodname></emphasis></para>
+ <para>Ignored if mode is not a client. If the type is a client then
+ a connection mechanism can be specified. Connector mechanisms
+ available are:-</para>
- <para>Port of proxy server.</para>
- </listitem>
- </itemizedlist>
+ <para><emphasis>encoding-sockets</emphasis> - Uses the encoding
+ mechanism (of value types) to serialize/deserialize objects, over
+ TCP/IP sockets.</para>
- <para>The following example sends a default length snapshot to the
- webserver.</para>
+ <para><emphasis>encoding-http</emphasis> - Uses the encoding
[... 289 lines stripped ...]