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 2013/05/23 10:00:47 UTC
svn commit: r1485602 - in /isis/site/trunk/content/applib-guide: ./
domain-services/ events/ how-tos/ images/ recognized-annotations/
recognized-methods/ reference/ reference/images/
reference/recognized-annotations/ supporting-features/ value-types/
Author: danhaywood
Date: Thu May 23 08:00:46 2013
New Revision: 1485602
URL: http://svn.apache.org/r1485602
Log:
converting applib guide to markdown (wip)
Added:
isis/site/trunk/content/applib-guide/domain-services/
isis/site/trunk/content/applib-guide/domain-services/000-about.md
isis/site/trunk/content/applib-guide/domain-services/how-to-09-010-How to register domain services, repositories and factories.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-09-010-How to register domain services, repositories and factories.md
isis/site/trunk/content/applib-guide/domain-services/how-to-09-020-How to write a typical domain service.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-09-020-How to write a typical domain service.md
isis/site/trunk/content/applib-guide/domain-services/how-to-09-030-How to use a generic repository.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-09-030-How to use a generic repository.md
isis/site/trunk/content/applib-guide/domain-services/how-to-09-040-How to write a custom repository.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-09-040-How to write a custom repository.md
isis/site/trunk/content/applib-guide/domain-services/how-to-09-050-How to use Factories.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-09-050-How to use Factories.md
isis/site/trunk/content/applib-guide/events/
isis/site/trunk/content/applib-guide/how-tos/000-about.md
isis/site/trunk/content/applib-guide/how-tos/how-to-08-010-Hiding, disabling or validating for specific users or roles.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/how-tos/how-to-080-010-Hiding, disabling or validating for specific users or roles.md
isis/site/trunk/content/applib-guide/reference/
isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md
isis/site/trunk/content/applib-guide/reference/Event.md
isis/site/trunk/content/applib-guide/reference/Recognized Methods and Prefixes.md
- copied unchanged from r1485103, isis/site/trunk/content/applib-guide/recognized-methods/Recognized Methods and Prefixes.md
isis/site/trunk/content/applib-guide/reference/Security.md
isis/site/trunk/content/applib-guide/reference/Utility.md
isis/site/trunk/content/applib-guide/reference/images/
- copied from r1485103, isis/site/trunk/content/applib-guide/images/
isis/site/trunk/content/applib-guide/reference/recognized-annotations/
- copied from r1485103, isis/site/trunk/content/applib-guide/recognized-annotations/
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Programmatic.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedAction.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedObject.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/QueryOnly.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/RegEx.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Render.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Resolve.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Title.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypeOf.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypicalLength.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/Value.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md
isis/site/trunk/content/applib-guide/supporting-features/000-about.md
isis/site/trunk/content/applib-guide/value-types/000-about.md
Removed:
isis/site/trunk/content/applib-guide/how-tos/how-to-080-010-Hiding, disabling or validating for specific users or roles.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-000-How to write Domain Services, Repositories and Factories.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-010-How to register domain services, repositories and factories.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-020-How to write a typical domain service.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-030-How to use a generic repository.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-040-How to write a custom repository.md
isis/site/trunk/content/applib-guide/how-tos/how-to-09-050-How to use Factories.md
isis/site/trunk/content/applib-guide/images/
isis/site/trunk/content/applib-guide/isis-applib.md
isis/site/trunk/content/applib-guide/recognized-annotations/
isis/site/trunk/content/applib-guide/recognized-methods/
isis/site/trunk/content/applib-guide/reference/images/architecture-perspective.png
isis/site/trunk/content/applib-guide/reference/images/composition-perspective.png
isis/site/trunk/content/applib-guide/value-types/010-intro.md
Modified:
isis/site/trunk/content/applib-guide/applib-guide-intro.md
isis/site/trunk/content/applib-guide/reference/recognized-annotations/000-about.md
Modified: isis/site/trunk/content/applib-guide/applib-guide-intro.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/applib-guide-intro.md?rev=1485602&r1=1485601&r2=1485602&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/applib-guide-intro.md (original)
+++ isis/site/trunk/content/applib-guide/applib-guide-intro.md Thu May 23 08:00:46 2013
@@ -1,25 +1,38 @@
Apache Isis Programming Model
=======
-*Apache Isis* is designed to allow programmers rapidly develop domain-driven applications following the [Naked
-Objects](http://en.wikipedia.org/wiki/Naked_Objects) pattern. It is made
-up of a core plus a number of components for each of the main APIs:
-objectstores, security, viewers and profilestores.
+*Apache Isis* is designed to allow programmers rapidly develop domain-driven applications following the [Naked Objects](http://en.wikipedia.org/wiki/Naked_Objects) pattern. It is made up of a core plus a number of components for each of the main APIs: objectstores, viewers, and security.
This guide is written for programmers looking to understand the
-programming conventions, annotations and supporting utilities within the
-*Apache Isis* application library (or *applib*), in order that the
-framework can correctly pick up and render the business rules and logic
-encoded within their domain objects.
-
-*Apache Isis* is hosted at the [Apache
-Foundation](http://incubator.apache.org/isis), and is licensed under
-[Apache Software License
-v2](http://www.apache.org/licenses/LICENSE-2.0.html).
-
-The conventions of the programming model are best described as
-'intentional' - they convey an intention as to how domain objects, their
-properties and behaviours, are to be made available to users. The
+*Apache Isis* programming mode: the programming conventions, annotations
+and supporting utilities supplied within the *Apache Isis* application library
+(or *applib*). Applications that follow these conventions enable the framework to correctly pick up and render the business rules and logic encoded within their domain objects.
+
+The guide breaks into three main parts:
+
+* How-tos
+
+ * [How-to write Domain Entities](./how-tos/000-about.html)
+
+ * [Domain Services, Repositories and Factories](./domain-services/000-about.html)
+
+ * [Value Types](./value-types/000-about.html)
+
+* [Supporting Features](./supporting-features/000-about.html)
+
+* Reference:
+
+ * [Recognized Methods and Prefixes](./reference/Recognized Methods and Prefixes.html)
+ * [Recognized Annotations](./reference/recognized-annotations/000-about.html)
+ * [DomainObjectContainer interface](./reference/DomainObjectContainer.html)
+ * [Security](./reference/Security.html)
+ * [Applib Utility Classes](./reference/Utility.html)
+ * [Applib Events](./reference/Event.html)
+
+You will note that to a large extent the conventions of the programming
+model can be described as 'intentional' - they convey an intention as to
+how domain objects, their properties and behaviours, are to be made
+available to users. But the
specific way in which those intentions are interpreted or implemented
will depend upon the framework, and/or the particular components or
options selected within that framework.
@@ -34,7 +47,3 @@ has *not* been defined as `@DropDownList
mechanism will suffice: a viewer might not support drop-down-lists but
instead might provide a capability to select from an `@Bounded` class by
typing the initial letters of the desired instance.
-
-This part of the guide is a set of chapters that provides how-to's for
-writing domain objects, by which we mean domain entities, value types,
-services and repositories/factories.
Added: isis/site/trunk/content/applib-guide/domain-services/000-about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/domain-services/000-about.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/domain-services/000-about.md (added)
+++ isis/site/trunk/content/applib-guide/domain-services/000-about.md Thu May 23 08:00:46 2013
@@ -0,0 +1,27 @@
+How to Write Domain Services, Repositories and Factories
+===========================================
+
+> How-to's relating to writing services, repositories and factories.
+
+This section contains how-to's for programming conventions that writing
+domain services (by which we also mean repositories and factories); ie
+everything that isn't a domain object or a value type.
+
+Domain services are instantiated once and once only by the framework,
+and are used to centralize any domain logic that does not logically
+belong in a domain entity or value. *Isis* will automatically inject
+services into every domain entity that requests them, and into each
+other.
+
+How-to's:
+
+* [How to register domain services, repositories and factories](./how-to-09-010-How to register domain services, repositories and factories.html)
+
+* [How to write a typical domain service](./how-to-09-020-How to write a typical domain service.html)
+
+* [How to use a generic repository](./how-to-09-030-How to use a generic repository.html)
+
+* [How to write a custom repository](./how-to-09-040-How to write a custom repository.html)
+
+* [How to use Factories](./how-to-09-050-How to use Factories.html)
+
Added: isis/site/trunk/content/applib-guide/how-tos/000-about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/how-tos/000-about.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/how-tos/000-about.md (added)
+++ isis/site/trunk/content/applib-guide/how-tos/000-about.md Thu May 23 08:00:46 2013
@@ -0,0 +1,221 @@
+title: How-tos
+
+How to write a basic Domain Entity or Service
+=============================================
+
+> How-to write a basic domain entity or service, specifying its
+> properties, collections and actions, and using some of the most
+> commonly-used additional semantics.
+
+Domain entities are instances of some class, usually (the vast majority)
+being persisted. Domain services are singletons that act typically act
+as factories and repositories. Domain entities have state in the form of
+properties and collections; domain services do not. Both domain entities
+and services have behaviour, in the form of actions.
+
+* [How to have a domain entity be a POJO](./how-to-01-010-How to have a domain entity be a POJO.html)
+
+* [How to have a domain service be a POJO](./how-to-01-020-How to have a domain service be a POJO.html)
+
+* [How to add a property to a domain entity](./how-to-01-030-How to add a property to a domain entity.html)
+
+* [How to specify a title for a domain entity](./how-to-01-040-How to specify a title for a domain entity.html)
+
+* [How to add a collection to a domain entity](./how-to-01-050-How to add a collection to a domain entity.html)
+
+* [How to add an action to a domain entity or service](./how-to-01-060-How to add an action to a domain entity or service.html)
+
+* [How to specify the icon for a domain entity](./how-to-01-070-How to specify the icon for a domain entity.html)
+
+* [How to specify the order in which properties or collections are displayed](./how-to-01-080-How to specify the order in which properties or collections are displayed.html)
+
+* [How to specify the order in which actions appear on the menu](./how-to-01-090-How to specify the order in which actions appear on the menu.html)
+
+* [How to make a property optional](./how-to-01-100-How to make a property optional.html)
+
+* [How to make an action parameter optional](./how-to-01-110-How to make an action parameter optional.html)
+
+* [How to specify the size of String properties](./how-to-01-120-How to specify the size of String properties.html)
+
+* [How to specify the size of String action parameters](./how-to-01-130-How to specify the size of String action parameters.html)
+
+* [How to specify names or descriptions for an action parameter](./how-to-01-140-How to specify names or descriptions for an action parameter.html)
+
+* [How to inject services into a domain entity or other service](./how-to-01-150-How to inject services into a domain entity or other service.html)
+
+* [How to create or delete objects within your code](./how-to-01-160-How to create or delete objects within your code.html)
+
+
+How to add business rules
+=========================
+
+> How-to add business rules to domain entities and services, controlling
+> whether a domain entity or service's class members are visible, if
+> they are enabled, and to validate arguments.
+
+Business rules can be added to domain objects in a number of ways. As
+well as the business logic encapsulated by domain object actions, the
+framework also supports a number of conventions that allow a domain
+entity or service's members to be made visible or hidden, to be enabled
+or disabled (greyed out), and to validate arguments when invoking an
+action, setting a new value for a property, or if adding a new element
+to a collection.
+
+Or, in other words: "see it, use it, do it".
+
+* [How to hide a property](./how-to-02-010-How to hide a property.html)
+
+* [How to hide a collection](./how-to-02-020-How to hide a collection.html)
+
+* [How to hide an action](./how-to-02-030-How to hide an action.html)
+
+* [How to specify that none of an object's members is visible](./how-to-02-040-How to specify that none of an object's members is visible.html)
+
+* [How to prevent a property from being modified](./how-to-02-050-How to prevent a property from being modified.html)
+
+* [How to prevent a collection from being modified](./how-to-02-060-How to prevent a collection from being modified.html)
+
+* [How to prevent an action from being invoked](./how-to-02-070-How to prevent an action from being invoked.html)
+
+* [How to specify that none of an object's members can be modified or invoked](./how-to-02-080-How to specify that none of an object's members can be modified or invoked.html)
+
+* [How to specify that an object is immutable](./how-to-02-090-How to specify that an object is immutable.html)
+
+* [How to validate user input for a property](./how-to-02-100-How to validate user input for a property.html)
+
+* [How to validate an object being added or removed from a collection](./how-to-02-110-How to validate an object being added or removed from a collection.html)
+
+* [How to validate an action parameter argument](./how-to-02-120-How to validate an action parameter argument.html)
+
+* [How to validate declaratively using MustSatisfy](./how-to-02-130-How to validate declaratively using MustSatisfy.html)
+
+
+How to provide drop-downs and default values
+============================================
+
+> How-to make actions easier to use from an end-user perspective, by
+> providing sets of choices and defaults.
+
+Invoking actions or setting properties requires that the user specify a
+valid value; of the correct type, and that passes any validation rules
+that may have been defined. To make things are easier for the user, you
+can provide lists of choices; viewers typically render these values in a
+drop-down list box.
+
+In a similar vein, there may be a default value for an action parameter;
+this can also be specified.
+
+
+* [How to specify a set of choices for a property](./how-to-03-010-How to specify a set of choices for a property.html)
+
+* [How to specify a set of choices for an action parameter](./how-to-03-020-How to specify a set of choices for an action parameter.html)
+
+* [How to specify that a class of objects has a limited number of instances](./how-to-03-030-How to specify that a class of objects has a limited number of instances.html)
+
+* [How to find an entity (for an action parameter or property) using auto-complete](./how-to-03-040-How to find an entity (for an action parameter or property) using auto-complete.html)
+
+* [How to specify default values for an action parameter](./how-to-03-050-How to specify default values for an action parameter.html)
+
+
+How to derive properties and collections, and other side-effects
+========
+
+The *Isis* viewers will automatically render the state of properties and
+collections, but the values of such need not be persisted; they can be
+derived from other information available to the object.
+
+* [How to make a derived property](./how-to-04-010-How to make a derived property.html)
+
+* [How to make a derived collection](./how-to-04-020-How to make a derived collection.html)
+
+* [How to inline the results of a query-only repository action](./how-to-04-030-How to inline the results of a query-only repository action.html)
+
+* [How to trigger other behaviour when a property is changed](./how-to-04-040-How to trigger other behaviour when a property is changed.html)
+
+* [How to trigger other behaviour when an object is added or removed](./how-to-04-050-How to trigger other behaviour when an object is added or removed.html)
+
+* [How to set up and maintain bidirectional relationships](./how-to-04-060-How to set up and maintain bidirectional relationships.html)
+
+
+How to provide additional UI hints
+==================================
+
+> How to override Isis' defaults for presentation.
+
+With the exception of value types for action parameters <!--(see ?)-->, Isis
+can normally infer a reasonable name for entity/service and its class
+members. However, these defaults can be overridden if required. One
+possible case is where the desired name is a reserved word in Java (eg
+"default", or "package").
+
+A slightly more advanced use-case is to specify an icon not for an
+entity's type, but for an entity instance. Typically this reflects that
+instance's state, eg with an overlay on top of the base icon. For
+example, this allows the user to distinguish between an Order that has
+been placed vs one that has been shipped.
+
+* [How to specify a name or description for an object](./how-to-05-010-How to specify a name or description for an object.html)
+
+* [How to specify a name or description for a property](./how-to-05-020-How to specify a name or description for a property.html)
+
+* [How to specify a name or description for a collection](./how-to-05-030-How to specify a name or description for a collection.html)
+
+* [How to specify names or description for an action](./how-to-05-040-How to specify names or description for an action.html)
+
+* [How to specify the icon for an individual objects state](./how-to-05-050-How to specify the icon for an individual objects state.html)
+
+
+
+How to deal with errors
+=======================
+
+> How to inform the user if an error occurs.
+
+Things go wrong. *Isis* handles many of the usual error conditions, but
+your app may also wish to notify the user also when something goes awry.
+
+* [How to deal with errors](./how-to-06-000-How to deal with errors.html)
+
+* [How to pass a messages and errors back to the user](./how-to-06-010-How to pass a messages and errors back to the user.html)
+
+* [How to deal with an unexpected error](./how-to-06-020-How to deal with an unexpected error.html)
+
+
+How to handle the entity persistence lifecycle
+==============================================
+
+> How to hook into the entity persistence lifecycle and handle specific
+> scenarios
+
+*Isis* automatically persists domain entities, performing both lazy
+loading and dirty object tracking. As an application programmer you can
+get visibility into and influence this behaviour.
+
+
+* [How to set up the initial value of a property programmatically](./how-to-07-010-How to set up the initial value of a property programmatically.html)
+
+* [How to insert behaviour into the object life cycle](./how-to-07-020-How to insert behaviour into the object life cycle.html)
+
+* [How to ensure object is in valid state](./how-to-07-030-How to ensure object is in valid state.html)
+
+* [How to specify that an object should not be persisted](./how-to-07-040-How to specify that an object should not be persisted.html)
+
+* [How to perform lazy loading](./how-to-07-050-How to perform lazy loading.html)
+
+* [How to perform dirty object tracking](./how-to-07-060-How to perform dirty object tracking.html)
+
+
+How to handle security concerns
+===============================
+
+> Further validation how-to's that apply across all class members
+
+This chapter has some additional recipes/how-tos relating to
+implementing business rules. They apply across all class members.
+
+* [Hiding, disabling or validating for specific users or roles](./how-to-08-010-Hiding, disabling or validating for specific users or roles.html)
+
+* [How to use Isis authorization manager](./how-to-08-020-How to use Isis authorization manager.html)
+
+
+
Added: isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md (added)
+++ isis/site/trunk/content/applib-guide/reference/DomainObjectContainer.md Thu May 23 08:00:46 2013
@@ -0,0 +1,163 @@
+DomainObjectContainer interface
+===============================
+
+> Provides a single point of contact from domain objects into the
+> *Apache Isis* framework.
+
+The `DomainObjectContainer` interface provides a single point of contact
+from domain objects into the *Isis* framework. It can also be used as a
+lightweight general purpose repository during prototyping.
+
+<table>
+<tr>
+ <th>Category</th>
+ <th>Method</th>
+ <th>Description</th>
+</tr>
+<tr>
+ <td>Object creation</td>
+ <td>newTransientInstance(Class\<T\>)</td>
+ <td>Creates new non-persisted object</td>
+</tr>
+<tr>
+ <td></td>
+ <td>newPersistentInstance(Class\<T\>)</td>
+ <td>Creates new object, will be persisted at end of action</td>
+</tr>
+<tr>
+ <td></td>
+ <td>newInstance(Class\<T\>, Object)</td>
+ <td>Creates object in state persistence state as that provided</td>
+</tr>
+<tr>
+ <td>Validation</td>
+ <td>isValid(Object)</td>
+ <td>whether object is valid</td>
+</tr>
+<tr>
+ <td></td>
+ <td>validate(Object)</td>
+ <td>reason why object is invalid (if any)</td>
+</tr>
+<tr>
+ <td>Generic Repository</td>
+ <td>allInstances(Class\<T\>)</td>
+ <td>All persisted instances of specified type</td>
+</tr>
+<tr>
+ <td></td>
+ <td>allMatches(Class\<T\>, Filter\<T\>)</td>
+ <td>All persistenced instances of specified type matching filter</td>
+</tr>
+<tr>
+ <td></td>
+ <td>allMatches(Class\<T\>, String)</td>
+ <td>All persisted instances with the specified string as their title</td>
+</tr>
+<tr>
+ <td></td>
+ <td>allMatches(Class\<T\>, Object)</td>
+ <td>All persisted instances matching object (query-by-example)</td>
+</tr>
+<tr>
+ <td></td>
+ <td>allMatches(Query\<T\>)</td>
+ <td>All instances satisfying the provided query</td>
+</tr>
+<tr>
+ <td></td>
+ <td>firstMatch(...)</td>
+ <td>As for allMatches(...), but returning first instance</td>
+</tr>
+<tr>
+ <td></td>
+ <td>uniqueMatch(...)</td>
+ <td>As for firstMatch(...), but requiring there to be only one match</td>
+</tr>
+<tr>
+ <td>Object persistence</td>
+ <td>isPersistent(Object)</td>
+ <td>whether object is persistent</td>
+</tr>
+<tr>
+ <td></td>
+ <td>persist(Object)</td>
+ <td>persist the transient object</td>
+</tr>
+<tr>
+ <td></td>
+ <td>persistIfNotAlready(Object)</td>
+ <td>persist the object (provided is not already persisted)</td>
+</tr>
+<tr>
+ <td></td>
+ <td>remove(Object)</td>
+ <td>remove the persisted object</td>
+</tr>
+<tr>
+ <td></td>
+ <td>removeIfNotAlready(Object)</td>
+ <td>remove the object (provided is not already transient)</td>
+</tr>
+<tr>
+ <td>Presentation</td>
+ <td>titleOf(Object)</td>
+ <td>Returns the title of the object.</td>
+</tr>
+<tr>
+ <td>Messages and warnings</td>
+ <td>informUser(String)</td>
+ <td>Inform the user</td>
+</tr>
+<tr>
+ <td></td>
+ <td>warnUser(String)</td>
+ <td>Warn the user about a situation, requiring acknowledgement.</td>
+</tr>
+<tr>
+ <td></td>
+ <td>raiseError(String)</td>
+ <td>Notify user of a serious application error, typically requiring further action on behalf of the user</td>
+</tr>
+<tr>
+ <td>Security</td>
+ <td>getUser()</td>
+ <td>The currently-logged on user</td>
+</tr>
+<tr>
+ <td>Properties</td>
+ <td>getProperty(String)</td>
+ <td>Value of configuration property</td>
+</tr>
+<tr>
+ <td></td>
+ <td>getPropertyNames()</td>
+ <td>All configuration properties available</td>
+</tr>
+<tr>
+ <td>Lazy loading, dirty object tracking (\*)</td>
+ <td>resolve(Object)</td>
+ <td>Lazy load object (overloaded to optionally load a property of object)</td>
+</tr>
+<tr>
+ <td></td>
+ <td>objectChanged(Object)</td>
+ <td>Mark object as dirty</td>
+</tr>
+<tr>
+ <td>Object store control (\*\*)</td>
+ <td>flush()</td>
+ <td>Flush all pending changes to object store</td>
+</tr>
+<tr>
+ <td></td>
+ <td>commit()</td>
+ <td>Commit all pending changes to object store</td>
+</tr>
+</table>
+
+
+> **Note**
+>
+> (\*) generally not necessary to call - performed by bytecode proxies
+> (\*\*) the use of these methods is discouraged - they are typically used only for tests
Added: isis/site/trunk/content/applib-guide/reference/Event.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/Event.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/Event.md (added)
+++ isis/site/trunk/content/applib-guide/reference/Event.md Thu May 23 08:00:46 2013
@@ -0,0 +1,14 @@
+Events
+======
+
+> The InteractionEvent hierarchy.
+
+Although not supported by the default programming model, the applib
+nevertheless defines an event hierarchy that characterizes all of the
+different types of interactions that can occur. This is used by the
+wrapper programming model, and is exploited by the JUnit viewer.
+
+The following UML class diagram shows the hierarchy of events:
+
+
+
Added: isis/site/trunk/content/applib-guide/reference/Security.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/Security.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/Security.md (added)
+++ isis/site/trunk/content/applib-guide/reference/Security.md Thu May 23 08:00:46 2013
@@ -0,0 +1,29 @@
+Security Classes
+================
+
+> A simple set of classes to represent the currently logged on user and
+> their roles.
+
+When the user logs onto an *Isis* application, the framework constructs a
+representation of their user and roles using classes from the applib.
+This allows the application to inspect and act upon those details if
+required.
+
+The user details are captured in the
+`org.apache.isis.applib.security.UserMemento` class ("memento" because it
+is a snapshot of their credentials at the point of logging on). The
+`UserMemento` class defines the following properties:
+
+- `name` (a `String`)
+
+- collection of roles (as `RoleMemento`)
+
+The `org.apache.isis.applib.security.RoleMemento` class in turn defines
+two properties:
+
+- `name` (a `String`)
+
+- `description` (a `String`)
+
+To obtain the current user, the application can call
+`DomainObjectContainer#getUser()`.
Added: isis/site/trunk/content/applib-guide/reference/Utility.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/Utility.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/Utility.md (added)
+++ isis/site/trunk/content/applib-guide/reference/Utility.md Thu May 23 08:00:46 2013
@@ -0,0 +1,38 @@
+Utility Classes
+===============
+
+> Simple utility classes for domain objects.
+
+The `org.apache.isis.applib.util` package has a number of simple utility
+classes designed to simplify the coding of some common tasks.
+
+Title creation
+--------------
+
+The `TitleBuffer` utility class is intended to make it easy to construct
+title strings (returned from the `title()` method). For example, it has
+overloaded versions of methods called `append()` and `concat()`.
+
+Reason text creation (for disable and validate methods)
+-------------------------------------------------------
+
+There are two different classes provided to help build reasons returned
+by `disableXxX()` and `validateXxx()` methods:
+
+- the `org.apache.isis.applib.util.ReasonBuffer` helper class
+
+- the `org.apache.isis.applib.util.Reasons` helper class
+
+For example:
+
+ public class Customer {
+ ...
+ public String validatePlaceOrder(Product p, int quantity) {
+ return Reasons.coalesce(
+ whetherCustomerBlacklisted(this),
+ whetherProductOutOfStock(p)
+ );
+ }
+ }
+
+Which you use (if any) is up to you.
Modified: isis/site/trunk/content/applib-guide/reference/recognized-annotations/000-about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/000-about.md?rev=1485602&r1=1485103&r2=1485602&view=diff
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/000-about.md (original)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/000-about.md Thu May 23 08:00:46 2013
@@ -1,8 +1,52 @@
Recognized Annotations
======================
-> All the annotations recognized in the *Apache Isis* default
-> programming model.
-
-This chapter defines the set of annotations that are recognised by the
-*Apache Isis* default programming model.
+* [ActionOrder](./ActionOrder.html)
+* [ActionSemantics](./ActionSemantics.html)
+* [Aggregated](./Aggregated.html)
+* [Audited](./Audited.html)
+* [AutoComplete](./AutoComplete.html)
+* [Bounded](./Bounded.html)
+* [Bulk](./Bulk.html)
+* [Debug](./Debug.html)
+* [Defaulted](./Defaulted.html)
+* [DescribedAs](./DescribedAs.html)
+* [Disabled](./Disabled.html)
+* [Encodable](./Encodable.html)
+* [EqualByContent](./EqualByContent.html)
+* [Exploration](./Exploration.html)
+* [Facets](./Facets.html)
+* [FieldOrder](./FieldOrder.html)
+* [Hidden](./Hidden.html)
+* [Idempotent (deprecated)](./Idempotent (deprecated).html)
+* [Ignore (deprecated)](./Ignore (deprecated).html)
+* [Immutable](./Immutable.html)
+* [Mask](./Mask.html)
+* [MaxLength](./MaxLength.html)
+* [MemberGroups](./MemberGroups.html)
+* [MemberOrder](./MemberOrder.html)
+* [MultiLine](./MultiLine.html)
+* [MustSatisfy](./MustSatisfy.html)
+* [Named](./Named.html)
+* [NotContributed](./NotContributed.html)
+* [NotInServiceMenu](./NotInServiceMenu.html)
+* [NotPersistable](./NotPersistable.html)
+* [NotPersisted](./NotPersisted.html)
+* [ObjectType](./ObjectType.html)
+* [Optional](./Optional.html)
+* [Paged](./Paged.html)
+* [Parseable](./Parseable.html)
+* [Plural](./Plural.html)
+* [Programmatic](./Programmatic.html)
+* [Prototype](./Prototype.html)
+* [PublishedAction](./PublishedAction.html)
+* [PublishedObject](./PublishedObject.html)
+* [QueryOnly](./QueryOnly.html)
+* [RegEx](./RegEx.html)
+* [Render](./Render.html)
+* [Resolve](./Resolve.html)
+* [Title](./Title.html)
+* [TypeOf](./TypeOf.html)
+* [TypicalLength](./TypicalLength.html)
+* [Value](./Value.html)
+* [ViewModel](./ViewModel.html)
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Programmatic.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Programmatic.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Programmatic.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Programmatic.md Thu May 23 08:00:46 2013
@@ -0,0 +1,24 @@
+@Programmatic
+-------------
+
+The `@Programmatic` annotation can be used to cause Apache Isis to
+complete ignore a class member. This means it won't appear in any
+viewer, its value will not be persisted, and it won't appear in any XML
+snapshots <!--(see ?)-->.
+
+A common use-case is to ignore implementation-level artifacts. For
+example:
+
+ public class Customer implements Comparable<Customer> {
+ ...
+ @Programmatic
+ public int compareTo(Customer c) {
+ return getSalary() - c.getSalary();
+ }
+ ...
+ }
+
+Note that `@Programmatic` does not simply imply `@Hidden` and `@NotPersisted`;
+it actually means that the class member will not be part of the Isis
+metamodel.
+
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedAction.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedAction.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedAction.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedAction.md Thu May 23 08:00:46 2013
@@ -0,0 +1,10 @@
+@PublishedAction
+----------------
+
+> **Support**
+>
+> * Requires the JDO/DataNucleus object store; not yet supported by other object stores.
+
+This annotation on an action causes an events to be published by the registered implementation of a `PublishingService`.
+
+A fuller description of the publishing architecture can be found [here](http://isis.apache.org/core/publishing-service.html).
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedObject.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedObject.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedObject.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/PublishedObject.md Thu May 23 08:00:46 2013
@@ -0,0 +1,10 @@
+@PublishedObject
+----------------
+
+> **Support**
+>
+> * Requires the JDO/DataNucleus object store; not yet supported by other object stores.
+
+This annotation on an entity type causes an events to be published by the registered implementation of a `PublishingService` if an instance of that type is inserted, updated or deleted .
+
+A fuller description of the publishing architecture can be found [here](http://isis.apache.org/core/publishing-service.html).
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/QueryOnly.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/QueryOnly.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/QueryOnly.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/QueryOnly.md Thu May 23 08:00:46 2013
@@ -0,0 +1,5 @@
+@QueryOnly (deprecated)
+-----------------------
+
+Equivalent to using `@ActionSemantics(Of.SAFE)` on an action.
+
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/RegEx.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/RegEx.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/RegEx.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/RegEx.md Thu May 23 08:00:46 2013
@@ -0,0 +1,45 @@
+@RegEx
+------
+
+The `@RegEx` annotation may be applied to any string property, or to any
+parameter within an action method. It can also be applied to any
+string-based value type. It serves both to validate and potentially to
+normalise the format of the input. `@Regex` is therefore similar in use
+to `@Mask` <!--(see ?)--> but provides more flexibility.
+
+The syntax is:
+
+`@RegEx(validation = "regEx string",
+ format = "regEx string", caseSensitive =
+ <true|false>)`
+
+Only the first parameter is required; the `format` defaults to "no
+formatting", and `caseSensitive` defaults to false.
+
+For example, on a property:
+
+ public class Customer {
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ public String getEmail() {}
+ ...
+ }
+
+Or, on a parameter:
+
+ public class Customer {
+ public void updateEmail(
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ @Named("Email") String email) {
+ ...
+ }
+ ...
+ )
+
+Or, on a value type:
+
+ @Value(...)
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ public class EmailAddress {
+ ...
+ }
+
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Render.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Render.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Render.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Render.md Thu May 23 08:00:46 2013
@@ -0,0 +1,38 @@
+@Render
+-------
+
+> **Support**
+>
+> * Supported by: Wicket viewer; not yet supported by other viewers.
+
+The `@Render` annotation is a hint for properties and collections to
+indicate that a value property should be rendered lazily (rather than
+eagerly, as usual), or that a reference property or collection should be
+rendered eagerly (rather than lazily, as usual).
+
+Viewers can use this to present the property/collection in an
+appropriate manner:
+
+- an `Order`'s `lineItems` collection might initially be rendered expanded
+ form so that the user could see a list of line items immediately
+ when the order is rendered. This is the most common use case.
+
+- a (reference) property of type `Address` might show the details of the
+ referenced `Address` in a box
+
+At the same time, an object store might use this to defer lazy loading
+of values that represent blobs or clobs.
+
+For example:
+
+ public class Order {
+ @Render(Type.EAGERLY)
+ public List<LineItem> getDetails() { ... }
+
+ ...
+ }
+
+For properties and collections there is some similarity between this
+concept and that of eager-loading as supported by some object stores.
+Indeed, some object stores may choose use their own specific annotations
+(eg a JDO default fetch group) in order to infer this semantic.
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Resolve.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Resolve.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Resolve.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Resolve.md Thu May 23 08:00:46 2013
@@ -0,0 +1,6 @@
+@Resolve (deprecated)
+---------------------
+
+The `@Resolve` annotation is deprecated, and has been replaced by the
+`@Render` annotation (with exact same semantics).
+
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Title.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Title.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Title.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Title.md Thu May 23 08:00:46 2013
@@ -0,0 +1,39 @@
+@Title
+------
+
+> **Support**
+>
+> * Supported by: Wicket viewer; partial support in other viewers.
+
+The `@Title` annotation is used to indicate which property or properties
+make up the object title. If more than one property is used, the order
+can be specified (using the same Dewey-decimal notation as used by
+`@MemberOrder`) and the string to use between the components can also be
+specified.
+
+For example:
+
+ public void Customer {
+ @Title(sequence="1.0")
+ public String lastName() { ... }
+ ...
+ @Title(sequence="1.5", prepend=", ")
+ public String firstName() { ... }
+ ...
+ @Title(sequence="1.7", append=".")
+ public String midInitial() { ... }
+ ...
+ }
+
+could be used to create names of the style "Bloggs, Joe K."
+
+It is also possible to annotate reference properties; in this case the
+title will return the title of the referenced object (rather than, say,
+its string representation).
+
+An additional convention for `@Title` properties is that they are hidden
+in tables (in other words, it implies `@Hidden(where=Where.ALL_TABLES)`.
+For viewers that support this annotation (for example, the Wicket
+viewer), this convention excludes any properties whose value is already
+present in the title column. This convention can be overridden using
+`@Hidden(where=Where.NOWHERE)`.
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypeOf.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypeOf.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypeOf.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypeOf.md Thu May 23 08:00:46 2013
@@ -0,0 +1,20 @@
+@TypeOf
+-------
+
+The `@TypeOf` annotation is used to specify the type of elements in a
+collection, when for whatever reason it is not possible to use generics.
+
+> **Note**
+>
+> Given that Apache Isis only supports Java 1.6 and later, it's not that
+> obvious what such a reason might be...
+
+For example:
+
+ public void AccountService {
+ @TypeOf(Customer.class)
+ public List errantAccounts() {
+ return CustomerDatabase.allNewCustomers();
+ }
+ ...
+ }
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypicalLength.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypicalLength.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypicalLength.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/TypicalLength.md Thu May 23 08:00:46 2013
@@ -0,0 +1,42 @@
+@TypicalLength
+--------------
+
+The `@TypicalLength` annotation indicates the typical length of a
+`String` property or `String` parameter in an action. It can also be
+specified for string-based value types.
+
+The information is generally used by the viewing mechanism to determine
+the space that should be given to that property or parameter in the
+appropriate view. If the typical length is the same as the `@MaxLength`
+<!--(see ?)--> then there is no need to specify `@TypicalLength` as well. If
+the value specified is zero or negative then it will be ignored.
+
+For example, for a property:
+
+ public class Customer {
+ @MaxLength(30)
+ @TypicalLength(20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ }
+
+Or, for a parameter:
+
+ public class CustomerRepository {
+ public Customer newCustomer(
+ @TypicalLength(20)
+ @Named("First Name") String firstName
+ ,@TypicalLength(20)
+ @Named("Last Name") String lastName) {
+ ...
+ }
+ ...
+ }
+
+Or, for value type:
+
+ @Value(...)
+ @TypicalLength(20)
+ public class FirstName {
+ ...
+ }
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/Value.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/Value.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/Value.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/Value.md Thu May 23 08:00:46 2013
@@ -0,0 +1,19 @@
+@Value
+------
+
+The `@Value` annotation indicates that a class should be treated as a
+value type rather than as a reference (or entity) type. It does this
+providing an implementation of a
+`org.apache.isis.applib.adapters.ValueSemanticsProvider`.
+
+For example:
+
+ @Value(semanticsProviderClass=ComplexNumberValueSemanticsProvider.class)
+ public class ComplexNumber {
+ ...
+ }
+
+The `ValueSemanticsProvider` allows the framework to interact with the
+value, parsing strings and displaying as text, and encoding/decoding
+(for serialization). <!--For more information, see ?.-->
+
Added: isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md (added)
+++ isis/site/trunk/content/applib-guide/reference/recognized-annotations/ViewModel.md Thu May 23 08:00:46 2013
@@ -0,0 +1,23 @@
+@ViewModel
+----------
+
+> **Support**
+>
+> * Not yet supported by any viewers
+
+The `@ViewModel` annotation allows the developer to declare that a domain
+object is intended to be used as a view model. As such, any changes to
+its structure are guaranteed to be backwardly compatible.
+
+The annotation was originally introduced to support a requirement of the
+RestfulObjects viewer which directly expose the domain objects as
+RESTful representations
+
+For example, a domain object that represents a summary of a Customer and
+their most recent Orders might be annotated as:
+
+ @NotPersistable
+ @ViewModel
+ public class CustomerAndOrdersViewModel {
+ ...
+ }
Added: isis/site/trunk/content/applib-guide/supporting-features/000-about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/supporting-features/000-about.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/supporting-features/000-about.md (added)
+++ isis/site/trunk/content/applib-guide/supporting-features/000-about.md Thu May 23 08:00:46 2013
@@ -0,0 +1,10 @@
+title: Supporting Features
+
+
+* [Clock](./01-Clock.html)
+
+* [Profiles](./02-Profiles.html)
+
+* [Fixtures and SwitchUser](./03-Fixtures and SwitchUser.html)
+
+* [XML Snapshots](./04-XML Snapshots.html)
Added: isis/site/trunk/content/applib-guide/value-types/000-about.md
URL: http://svn.apache.org/viewvc/isis/site/trunk/content/applib-guide/value-types/000-about.md?rev=1485602&view=auto
==============================================================================
--- isis/site/trunk/content/applib-guide/value-types/000-about.md (added)
+++ isis/site/trunk/content/applib-guide/value-types/000-about.md Thu May 23 08:00:46 2013
@@ -0,0 +1,49 @@
+Value Types
+===========
+
+> Built-in value types, writing your own value types, and supporting
+> third-party value types.
+
+The state of any given entity is characterized by properties <!--(?)--> and
+collections <!--(?)-->. A collections is a one-to-many reference to another
+entities, while a property is either a one-to-one reference to another
+entity, or it is a value.
+
+But what's a value? Well, it's an atomic piece of state. A string is a
+value, so is a number, so is a date. Values should be designed to be
+immutable (though some system value types, such as java.util.Date,
+famously are not).
+
+*Isis* supports all the standard JDK value types, and defines a number
+of its own (eg Percentage and Color). *Isis* also allows you to define
+your own value types, such as `LastName`, or `Celsius`, or `ComplexNumber`.
+
+It's also possible to make Isis integrate with third-party
+value types. *Isis* provides one such integration, with
+[JodaTime](http://joda-time.sourceforge.net/).
+
+For more information, see:
+
+* [Built-in Value Types](./value-types/020-Built-in Value Types.html)
+
+* [Custom Value Types](./value-types/030-Custom Value Types]
+
+* [Third-party Value Types](./value-types/04-Third-party Value Types.html)
+
+> **Note**
+>
+> *Isis*' support for a particular value type does not necessarily imply
+> that there is a custom widget for that type in a particular viewer.
+> Rather, it means that the state of the object can be serialized, is
+> expected to have equal-by-content semantics, and is expected to be
+> immutable. It may also be parseable from a string.
+
+> **Note**
+>
+> Also, if using the JDO/DataNucleus ObjectStore, you may also need to perform additional DataNucleus-specific configuration if you want the data to be persisted in a SQL datatype other than SQL Blob (ie a serializable byte array).
+
+
+
+
+
+