Who this Guide is For

Return-Path: X-Original-To: apmail-incubator-isis-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-isis-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2CB1C1763 for ; Tue, 26 Apr 2011 22:38:44 +0000 (UTC) Received: (qmail 92933 invoked by uid 500); 26 Apr 2011 22:38:44 -0000 Delivered-To: apmail-incubator-isis-commits-archive@incubator.apache.org Received: (qmail 92918 invoked by uid 500); 26 Apr 2011 22:38:44 -0000 Mailing-List: contact isis-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: isis-dev@incubator.apache.org Delivered-To: mailing list isis-commits@incubator.apache.org Received: (qmail 92911 invoked by uid 99); 26 Apr 2011 22:38:44 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 26 Apr 2011 22:38:44 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 26 Apr 2011 22:38:40 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 4A2F52388A6B; Tue, 26 Apr 2011 22:38:20 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: 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... Date: Tue, 26 Apr 2011 22:38:19 -0000 To: isis-commits@incubator.apache.org From: danhaywood@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110426223820.4A2F52388A6B@eris.apache.org> 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 @@ Apache Isis is designed to allow programmers rapidly develop domain-driven applications following the Naked Objects - 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 Apache + pattern. It is made up of a core framework that supports supports various + viewers, along with APIs and implementations relating + to security, the programming model, the runtime (persistence) and profile + stores (user preferences). Apache Isis is hosted at + the Apache Foundation, and is licensed under Apache Software License v2. - This guide is written for ... - + 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. - + + Who this Guide is For - - Introduction + This guide is written for deployers looking to configure + Isis to run using the default runtime, in any of + the supported configurations. It is divided into the following + parts: + + *** - - *** yada yada - + This part of the guide *** + - - *** + + *** - *** yada yada + This part of the guide *** + - The guide is divided into *** parts: + + *** - - - *** Introduction + This part of the guide *** + + + - This part of the guide discusses the principles and patterns - of the default runtime. - + + How this Guide relates to other Documentation - - *** Architecture + The core documentation + [oai:core] describes common modules, including + reusable classes that make up the core runtime + [oai.core:runtime]. This module, the default runtime, + makes use of these classes, as well as other components. It also defines + a number of its own sub-APIs. + + - 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. - + + Core Concepts - - APIs + - This part of the guide goes the (sub-)APIs - that the runtime exposes - + + IsisContext - - Default Implementations + Context - This part of the guide outlines the default implementations of - the (sub-)APIs. - + 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. - - Objectstore Deployments + Each execution context will have its own Persistor, Message Broker + and Update Notifier. - This part of the guide describes how to configure the default - runtime to run with an objectstore. - + The Reflector and Configuration are shared among all execution + contexts. - - Client/Server Deployment + Persistor - This part of the guide describes how to configure the default - runtime to instead run in client/server mode. - - + 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. - *** - - This guide describes the deployment options that are available - through using the default implementations of the core module - APIs, for the most common viewers - (DnD and HTML). 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. - - + Identity map - - *** + 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. - - *** yada yada - + 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. - - *** + - *** yada yada + - - - - Modules - - + + Bootstrapping using installer-registry.properties - + - - Runtime Module + + Scopes + + + + + + + - - Scopes + + IdentityMap - + - + 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 - - - - - + + - - + + Profile Stores - - Bytecode Provider API + - + + - + + Exploration vs Prototype Modes - The default runtime for Apache Isis - 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. + - 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. + + + - - + + Modules - - Bootstrapping + + - - - + + + + - Runtime + Runtime Module @@ -262,111 +259,103 @@ - IsisContext - - Context - - 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. - - Each execution context will have its own Persistor, Message - Broker and Update Notifier. - - The Reflector and Configuration are shared among all execution - contexts. - - Persistor - - 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. - - Isis + Bytecode Provider API - - - Oid + - - + The default runtime for Apache Isis + 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. - - - + 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. - - Resolved State + + - - - - + + Bootstrapping - - Version + - - - - + - - + The first thing that happens is the logging is set up so that + everything can be logged. This attempts to load + logging.properties from the + config 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. - - - - - + 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 installer-registry.properties 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. - Identity map + Now the container knows what components are available a series + of option handlers (OptionHandler) 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. - 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. - - 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. + The last step before bootstrapping starts is to prepare the + ground for using congfiguration properties. Configuration details are + loaded by a ConfigurationBuilder object and + will be subsequently placed in an immutable + IsisConfiguration object. Immediately after + this has been created each handler is visited so that it can, via its + primeConfigurationBuilder 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. - + Now that the ground has been prepared it is time for the + bootstrapping to begin. This is done via a call to the + bootstrapIsis method, which is where the + process differs for the Isis container and the web server. - - - - Services Installer Services are registered with the Framework at startup via the properties file, using the services properties. The services property itself dictates which service classes are to be instantiated at startup, for example: - isis.services = bom.BookingFactory, bom.CustomerFactoryAndRepository, \ - bom.LocationFactoryAndRepository - + isis.services = com.mycompany.myapp.dom.BookingFactory,\ + com.mycompany.myapp.dom.CustomerFactoryAndRepository, \ + com.mycompany.myapp.dom.LocationFactoryAndRepository The prefix 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. - - isis.services.prefix = bom -isis.services = BookingFactory, CustomerFactoryAndRepository, \ - LocationFactoryAndRepository - + to the previous example: - + isis.services.prefix = com.mycompany.myapp.dom +isis.services = BookingFactory, CustomerFactoryAndRepository, LocationFactoryAndRepository @@ -420,22 +409,6 @@ isis.fixtures = BookingsFixture, Perspec - Identity Map - - 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 - - - - - - - Creating Adapters Numerous methods exist in the persistor (see @@ -490,433 +463,58 @@ isis.fixtures = BookingsFixture, Perspec - What makes up a PersistenceSession + Configuration Loading - + *** explain the principle, how we construct from the "id" of the + installer. - - - - - + - - - Launcher + The configuration file (isis.properties) 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. - + The configuration file isis.properties 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. - + -r (or --persistor) hibernate will cause + persistor.properties and persistor_hibernate.properties to be + used - 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. + -t (or --type) client will cause client.properties to be used - In essense we are running Java with the Isis class like - this + -v (or --viewer) dnd will cause + viewer.properties and viewer_dnd.properties to be used - $ java -cp <classpath> org.apache.isis.runtime.IsisObject - <parameters...> + -x (or -- connector) xstream-sockets will cause + transport.properties, + transport_sockets.properties, + protocol.properties and + protocol_xstream.properties to be loaded; because + of the way that connector is implemented it will also load + persistor.properties and persistor_xstream-sockets.properties + too. - however we typically use a script like the one created by the - archetype so we can run more easily, eg + In addition a particular file can be selected with the -c + switch. For example - $ ./isis.sh <parameters...> - - The Isis class immediately starts up the logging so that log - messages are never lost. Next the - InstallerLookup object is instantiated. This - loads up all the installers that can be found on the classpath, which - are listed in installer-registry.properties . (In - the source tree, this file physically resides in - core/runtime/src/main/resources/). 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. - - 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. - - - - - - - - - - If you are asked from diagnostic information then run Apache - Isis as follows to capture details about your machine, configuration - and Isis. - - $ isis.sh --diagnostics > diagnostics.txt - - - - - - - - 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 installer-registry.properties which is part - of the runtime-4.0.jar file. - - During start-up Isis loads in a number of configuration files. - The main file, isis.properties, 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 - - -v dnd -r xml - - specifies that the viewer is to be the drag and drop (dnd) 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 - viewer.properties, viewer_dnd.properties, - persistor.xml and persistor_xml.properties and will load them - if found. - - - - - - - Class - - The bootstrapper is the class - org.apache.isis.runtime.Isis 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). - - There is also an alternative bootstrapper, - org.apache.isis.webserver.WebServer. - - - - *** can also use org.apache.Isis - just delegates to - org.apache.isis.runtime.Isis. - - - - - - Configuration - - -c <config file> ---config <config file> - - Loads in the specified configuration file, in addition to - isis.properties and the properties files - relating to the installed component. - - - - Disable splash - - -s ---nosplash - - Prevents the splash screen from being displayed during start - up. - - - - Help - - -h ---help - - Prints out the options that are available. This is dynamic so - that only the components that can be used are listed. - - - - Logging - - 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. - - -quiet - - Quiet reduces logging to show errors only. - - -verbose - - Increases logging to show information about the system as it - runs. - - -debug - - 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. - - - - Deployment Type (or Mode) - - -t <mode> ---type <mode> - - The framework is started up in one of several different - deployment modes, as listed below: - - exploration - 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. - - prototype - 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. - - single-user - Single user mode runs the - system for a single user with object persistence. - - client - Client mode provides multiple - users access to a server. With this mode selected the - connection option must also be - specified. - - server-exploration - Server mode, but all - clients will automatically be logged in as the 'exploration' user - (or as LoginFixture is present). - - server-prototype - Server mode, but if a - LoginFixture is present then all clients will - automatically be logged in as this user. - - server - Server mode runs Isis as a - server for multiple clients. With this mode selected the - connection option must also be - specified. - - If no mode is specified, the framework will start up in - prototype mode. - - - - Overridden properties - - -D property=value - - 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. - - - - Password - - -p <password> ---password <password> - - Ignored if type is prototype or not used with the user option - below. - - Uses the specified password when logging the user in with the - username specified with --user. - - - - Persistor - - -r <persistor> ---persistor <persistor> - - Ignored if type is client. - - 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. - - in-memory - 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. - - xml - 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. - - <class name> - By specifying a - class name the boot loader will load up that class as the - persistor. - - - - Remote connector - - -x <connector> ---connector <connector> - - Ignored if mode is not a client. If the type is a client then - a connection mechanism can be specified. Connector mechanisms - available are:- - - encoding-sockets - Uses the encoding - mechanism (of value types) to serialize/deserialize objects, over - TCP/IP sockets. - - encoding-http - Uses the encoding - mechanism (of value types) to serialize/deserialize objects, over - HTTP. - - serializing-sockets - Uses Java - serialization (of value types) to serialize/deserialize objects, - over TCP/IP sockets. - - xstream-sockets - Uses the Xstream - library to serialize/deserialize objects to/from XML for simple - stream communications, over TCP/IP sockets. - - - - User - - -u <user name> ---user <user name> - - Ignored if type is prototype. - - 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. - - - - Viewer - - -v <viewer> ---viewer <viewer> - - 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. - - dnd - Drag and Drop viewer - - html - Web browser viewer - accessed via - standard web browser such as FireFox, Internet Explorer or - Opera - - encoding-sockets - Uses the encoding - mechanism (of value types) to serialize/deserialize objects, over - TCP/IP sockets. - - encoding-http - Uses the encoding - mechanism (of value types) to serialize/deserialize objects, over - HTTP. - - serializing-sockets - Uses Java - serialization (of value types) to serialize/deserialize objects, - over TCP/IP sockets. - - xstream-sockets - Uses the Xstream - library to serialize/deserialize objects to/from XML for simple - stream communications, over TCP/IP sockets. - - <class name> - By specifying a - class name the boot loader will load up that class as the - viewer - - - - - Configuration Loading - - *** explain the principle, how we construct from the "id" of the - installer. - - - - - - The configuration file (isis.properties) 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. - - The configuration file isis.properties 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. - - -r (or --persistor) hibernate will cause - persistor.properties and persistor_hibernate.properties to be - used - - -t (or --type) client will cause client.properties to be used - - -v (or --viewer) dnd will cause - viewer.properties and viewer_dnd.properties to be used - - -x (or -- connector) xstream-sockets will cause - transport.properties, - transport_sockets.properties, - protocol.properties and - protocol_xstream.properties to be loaded; because - of the way that connector is implemented it will also load - persistor.properties and persistor_xstream-sockets.properties - too. - - In addition a particular file can be selected with the -c - switch. For example - - -c mysettings.properties + -c mysettings.properties @@ -1109,6 +707,10 @@ isis.fixtures=ExpenseTypes, Employees, E Users + *** this is also mentioned in isis-security.file... + + + 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 - + Runtime Module @@ -1139,101 +741,117 @@ isis.fixtures=ExpenseTypes, Employees, E - 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. - - The Isis container is run using the Isis - class from the core-runtime module. - - Another way to run Isis is in a independent web container like - Tomcat or WebSphere. This process is dealt with later. - - General process + *** Component loggers - *** this material is probably better in the runtime module ... - however we should have something here that describes the main concepts - and classes. + *** split this out to the respective modules. - + 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:- - The first thing that happens is the logging is set up so that - everything can be logged. This attempts to load - logging.properties from the - config 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. + + + The object persistor - + ObjectPersistorLogger + + + + The object store - + ObjectStoreLogger + + + + The distibution interface - + DistributionLogger + + + + 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: + + ObjectAdapterPersistor persistor = new ObjectStorePersistor(); +isis.setObjectPersistor(persistor); + + with this, which will log request to the persistor the sever-persistor.log + file: + + ObjectAdapterPersistor persistor = new ObjectStorePersistor(); +persistor = new ObjectManagerLogger(persistor, "server-persistor.log"); +isis.setObjectPersistor(persistor); + + 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. + + + Defining a logger - 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 installer-registry.properties 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. + To define a logger extend the Logger class, providing a + suitable constructor, and implement the + getDecoratedClass so it passes back the + Class 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: - Now the container knows what components are available a series - of option handlers (OptionHandler) 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. + + + void log(String + message) - The last step before bootstrapping starts is to prepare the - ground for using congfiguration properties. Configuration details are - loaded by a ConfigurationBuilder object and - will be subsequently placed in an immutable - IsisConfiguration object. Immediately after - this has been created each handler is visited so that it can, via its - primeConfigurationBuilder 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. + output a log entry with the specified message. + - Now that the ground has been prepared it is time for the - bootstrapping to begin. This is done via a call to the - bootstrapIsis method, which is where the - process differs for the Isis container and the web server. + + void log(String message, Object + result) - + 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. + - - - + + void close() + - - Object Store API + closes the file that is being written to. + + - - *** - + - - + - + - + + + - - TODO: tidy up the following paras, were just copied/pasted in - from APT - + + Bytecode Enhancement API @@ -1252,40 +870,43 @@ isis.fixtures=ExpenseTypes, Employees, E - Alternative Implementations + Persistor API - Writing your own Object Store + Object Store API - When a object is persisted the object store's - createCreateObjectCommand 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 execute method that is called on the - command, and this command runs an insert command agains the the - database. - - - - - Profile Store API and Implementations + + Writing your own Object Store + + *** do we want to include this section ... it'll be somewhat + long! - - *** - + + + When a object is persisted the object store's + createCreateObjectCommand 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 execute method that + is called on the command, and this command runs an insert command + agains the the database. + + + + - + Profile Store API @@ -1322,561 +943,609 @@ isis.fixtures=ExpenseTypes, Employees, E - - TODO: tidy up the following paras, were just copied/pasted in - from APT - + + + To store profiles (during exploration) for users the a profile + store must be specified. + + On the command line use -e xml to store them in an XML. + + Without this the profile will simply be kept in memory, and lost + on exit. - *** + + Setting up Perspectives (Profile Fixtures) + + + + + + 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. + + 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). + + 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 saveAsDefault(), rather than + saveForUser() for a named user, as shown + below. + + 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); + } +} + + + 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. + + + + + + Webapp Module + + + + The webapp module is a small module that provides reusable servlet + context listeners and filters to webapp viewers. They include: + + + + IsisWebAppBootstrapper which is a + servlet context listener to bootstrap an Isis runtime and bind to + the servlet context + + + + IsisSessionFilter which is a filter + used to creating an IsisSession for each request (the Open session + in View pattern) + + + + ResourceServlet which serves up static + content from the specified resource + + + + StaticContentFilter which decorates + static content with headers for caching + + + + + The ResourceServlet and + StaticContentFilter will likely move back to + core framework because they are likely to be of use to most runtime + implementations. + + + 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. + + + + + + Webserver Module + + + + The webserver module is intended to make it easy to run + webapp-based viewers, using the webapp as defined in + src/main/webapp/WEB-INF/web.xml. + + 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. + + An alternative would be to use mvn jetty:run; this + module is for when you'd rather just run a standalone program (ie, with + a main() in it) without the overhead of + Maven. + + + + + + There is also an alternative bootstrapper, + org.apache.isis.webserver.WebServer. + + + + + + + + + + + + Properties + + The embedded web server (implemented by Jetty) has only one + properties + + isis.embedded-web-server.port=8080 + + Which specifies the port to use when prototyping. + + + + + + Remoting Modules + + + + + + + + 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. + + The Isis container is run using the Isis + class from the core-runtime module. + + Another way to run Isis is in a independent web container like + Tomcat or WebSphere. This process is dealt with later. + + + + + + + + + Runtime APIs - - + + Bytecode Enhancement API - - Alternative Implementations + - + + - + + Persistor API and Object Store API - - + + *** + - To store profiles (during exploration) for users the a profile - store must be specified. - - On the command line use -e xml to store them in an XML. + - Without this the profile will simply be kept in memory, and lost - on exit. + + TODO: tidy up the following paras, were just copied/pasted in + from APT + + - - Runtime Module + + Deployment - + + Running in Development - + *** ie, not deployed, just running immediately. - + + Bootstrapping (Isis launcher) - - Component loggers + - 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:- + - - - The object persistor - - ObjectPersistorLogger - + 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. - - The object store - - ObjectStoreLogger - + In essense we are running Java with the Isis class like + this: - - The distibution interface - - DistributionLogger - - + $ java -cp <classpath> + org.apache.isis.runtimes.dflt.runtime.Isis + <parameters...> - 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: + however we typically use a script like the one created by the + archetype so we can run more easily, eg - ObjectAdapterPersistor persistor = new ObjectStorePersistor(); -isis.setObjectPersistor(persistor); + $ ./isis.sh <parameters...> - with this, which will log request to the persistor the sever-persistor.log - file: + The Isis class immediately starts up the logging so that log + messages are never lost. Next the + InstallerLookup object is instantiated. This + loads up all the installers that can be found on the classpath, which + are listed in installer-registry.properties . (In + the source tree, this file physically resides in + core/runtime/src/main/resources/). 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. - ObjectAdapterPersistor persistor = new ObjectStorePersistor(); -persistor = new ObjectManagerLogger(persistor, "server-persistor.log"); -isis.setObjectPersistor(persistor); + 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. - 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. + - - Defining a logger + - To define a logger extend the Logger class, providing a - suitable constructor, and implement the - getDecoratedClass so it passes back the - Class 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: + - - - void log(String - message) + - output a log entry with the specified message. - + If you are asked from diagnostic information then run Apache + Isis as follows to capture details about your machine, configuration + and Isis. - - void log(String message, Object - result) + $ isis.sh --diagnostics > diagnostics.txt - 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. - + - - void close() - + - closes the file that is being written to. - - + - + 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 installer-registry.properties which is part + of the JAR file for [oai.runtimes.dflt:runtime] + module. - + During start-up Isis loads in a number of configuration files. + The main file, isis.properties, 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 - + -v dnd -r xml - - - + specifies that the viewer is to be the drag and drop (dnd) 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 + viewer.properties, viewer_dnd.properties, + persistor.xml and persistor_xml.properties and will load them + if found. - - Diagnostics (Logging) + - Snapshot appenders - - 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. - - All the snapshot appends support the same basic - properties:- + Class - - - addInfo - + The bootstrapper is the class + org.apache.isis.runtime.Isis 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). - (boolean) indicates whether to prepend details about the - machine, os and Java to log, eg + - 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 - + - - bufferSize - + *** can also use org.apache.Isis - just delegates to + org.apache.isis.runtime.Isis. - (integer) the number of events to write out to the - snapshot. Defaults to 512 events. - + + - - locationInfo - + + Configuration - (boolean) whether to capture the details of where in the - code the event was generated. Note - capturing this information - can be quite expensive. - + -c <config file> +--config <config file> - - evaluatorClass - + Loads in the specified configuration file, in addition to + isis.properties and the properties files + relating to the installed component. + - (org.apache.log4j.spi.TriggeringEventEvaluator) - 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. - - When not trigger is specified a default trigger is applied - that triggers a snapshot when an event of level ERROR or FATAL - occurs. - - + + Disable splash - - File snapshot appender + -s +--nosplash - The FileSnapshotAppender writes the - snapshot to timestamped file. The following properties can be - specified:- - - - - directory - - The directory path where the files are to be created. If - none is specified then the working directory will be - used. - - - - extension - - The extension type to append to the file name. - - - - fileName - - The base name of the log file, which will have timestamp - appended. Defaults to 'log-snapshot-'. - - - - The following example writes xml snapshots to the logs - directory to files ending with '.xml'. - - 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 - - - - Popup snapshot appender - - The PopupSnapshotAppender displays a - popup dialog showing the snapshot. - - - - - - - - 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. - - 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 - - + Prevents the splash screen from being displayed during start + up. + - - Email snapshot appender + + Help - The SmtpSnapshotAppender generates an - email with the snapshot in it and sends it to a specified - recipient. The following properties can be specified:- + -h +--help - - - server + Prints out the options that are available. This is dynamic so + that only the components that can be used are listed. + - Address of the email server - + + Logging - - port + 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. - The port the server listen on for SMTP requests. - Defaults to port 25. - + -quiet - - recipient + Quiet reduces logging to show errors only. - Email address to send the snapshot to. - + -verbose - - domain + Increases logging to show information about the system as it + runs. - 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. - - + -debug - 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. + 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. + - 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 - + + Deployment Type (or Mode) - - Socket snapshot appender + -t <mode> +--type <mode> - The SocketSnapshotAppender - establishes a socket connection to a server and passes across the - the snapshot. This is designed to be used with - SnapshotServer, which collects collects - snapshots from multiple clients. + The framework is started up in one of several different + deployment modes, as listed below: - The following example sends an XML snapshot to a server on a - private network. + exploration - 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. - 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 + prototype - 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. - The snaphot server should be directed to a maching running - the server. The server is run using the following command: + single-user - Single user mode runs the + system for a single user with object persistence. - java -cp isis.jar org.apache.isis.utility.logging.SnapshotServer + client - Client mode provides multiple + users access to a server. With this mode selected the + connection option must also be + specified. - + server-exploration - Server mode, but all + clients will automatically be logged in as the 'exploration' user + (or as LoginFixture is present). - The server needs a properties file with the following - properties defined (with the prefix - isis.snapshotserver.):- + server-prototype - Server mode, but if a + LoginFixture is present then all clients will + automatically be logged in as this user. - - - server + server - Server mode runs Isis as a + server for multiple clients. With this mode selected the + connection option must also be + specified. - Address of the server. - + If no mode is specified, the framework will start up in + prototype mode. + - - port + + Overridden properties - The port the server listens on for logging requests. - Defaults to port 9289. - + -D property=value - - directory + 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. + - The directory path where the transferred files are to be - saved. If none is specified then the working directory will be - used. - + + Password - - fileName + -p <password> +--password <password> - The base name of the log file, which will have timestamp - appended. Defaults to 'log-snapshot-'. - + Ignored if type is prototype or not used with the user option + below. - - extension + Uses the specified password when logging the user in with the + username specified with --user. + - The extension type to append to the file name. - - + + Persistor - An example configuration would be:- + -r <persistor> +--persistor <persistor> - isis.snapshotserver.port=12345 -isis.snapshotserver.directory=logs -isis.snapshotserver.filename=log -isis.snapshotserver.extension=xml - + Ignored if type is client. - - Web snapshot appender + 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. - The WebSnapshotAppender sends the - snapshot to a web server. The following properties can be - specified:- + in-memory - 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. - - - url + xml - 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. - URL of server to post data to (including the protocol - 'http'). - + <class name> - By specifying a + class name the boot loader will load up that class as the + persistor. + - - proxyAddress + + Remote connector - Address of web proxy if one is being used. - + -x <connector> +--connector <connector> - - proxyPort + Ignored if mode is not a client. If the type is a client then + a connection mechanism can be specified. Connector mechanisms + available are:- - Port of proxy server. - - + encoding-sockets - Uses the encoding + mechanism (of value types) to serialize/deserialize objects, over + TCP/IP sockets. - The following example sends a default length snapshot to the - webserver. + encoding-http - Uses the encoding [... 289 lines stripped ...]