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 2015/11/19 20:18:27 UTC
isis git commit: ISIS-1250: more docs, this time on schemas
Repository: isis
Updated Branches:
refs/heads/ISIS-1250 4b891285b -> d409a71ad
ISIS-1250: more docs, this time on schemas
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/d409a71a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/d409a71a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/d409a71a
Branch: refs/heads/ISIS-1250
Commit: d409a71adef0e6b6868ae516108533214889925c
Parents: 4b89128
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Nov 19 19:18:23 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Nov 19 19:18:23 2015 +0000
----------------------------------------------------------------------
..._annotations_manpage-XmlJavaTypeAdapter.adoc | 6 +-
.../_rg_annotations_manpage-XmlRootElement.adoc | 5 +-
.../main/asciidoc/guides/_rg_schema-aim.adoc | 62 ++++++++++-
.../main/asciidoc/guides/_rg_schema-common.adoc | 103 ++++++++++++++++++-
.../asciidoc/guides/_rg_schema-utilities.adoc | 6 +-
.../src/main/asciidoc/guides/_rg_schema.adoc | 15 ++-
.../_ug_core-concepts_building-blocks.adoc | 100 +++++++++++++++---
7 files changed, 268 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
index 91c2ee9..4e16c5f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
@@ -6,9 +6,9 @@
The JAXB `@XmlJavaTypeAdapter` annotation (`1.11.0-SNAPSHOT`) is used with the framework-provided
-`PersistentEntityAdapter` to instruct JAXB to serialize references to persistent entities into a canonical `<oid-dto>`
-element: basically a formal XML equivalent to the `Bookmark` provided by the
-xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
+`PersistentEntityAdapter` to instruct JAXB to serialize references to persistent entities using the canonical
+`OidDto` complex type: the object's type and its identifier. This is the formal XML equivalent to the `Bookmark`
+provided by the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
index 604c034..06e8799 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
@@ -32,8 +32,9 @@ all the code by hand
The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
with the xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
-framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities into the
-`<oid-dto>` element as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema].
+framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities using the
+`oidDto` complex type (as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema]):
+the object's type and its identifier.
[TIP]
====
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
index d898b7e..5a3c528 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
@@ -5,4 +5,64 @@
:_imagesdir: images/
-NOTE: TODO
\ No newline at end of file
+NOTE: TODO
+
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema targetNamespace="http://isis.apache.org/schema/aim"
+ elementFormDefault="qualified"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://isis.apache.org/schema/aim"
+ xmlns:common="http://isis.apache.org/schema/common">
+
+ <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
+
+ <xs:element name="actionInvocationMementoDto">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="metadata">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="transactionId" type="xs:string"/>
+ <xs:element name="sequence" type="xs:int"/>
+ <xs:element name="timestamp" type="xs:dateTime"/>
+ <xs:element name="target" type="common:oidDto"/>
+ <xs:element name="targetClass" type="xs:string"/>
+ <xs:element name="targetAction" type="xs:string"/>
+ <xs:element name="actionIdentifier" type="xs:string"/>
+ <xs:element name="user" type="xs:string"/>
+ <xs:element name="title" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ <xs:element name="payload">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="parameters">
+ <xs:complexType>
+ <xs:sequence maxOccurs="unbounded">
+ <xs:element name="param" type="paramDto"/>
+ </xs:sequence>
+ <xs:attribute name="num" use="required" type="xs:int"/>
+ </xs:complexType>
+ </xs:element>
+ <xs:element name="return" type="common:valueDto" minOccurs="0" maxOccurs="1"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:complexType name="paramDto">
+ <xs:sequence>
+ <xs:element name="value" type="common:valueDto"/>
+ </xs:sequence>
+ <xs:attribute name="parameterName" use="required" type="xs:string"/>
+ <xs:attribute name="parameterType" use="required" type="common:valueType"/>
+ <xs:attribute name="null" use="optional" type="xs:boolean"/>
+ </xs:complexType>
+</xs:schema>
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
index 086c397..aedf188 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
@@ -5,13 +5,106 @@
:_imagesdir: images/
-NOTE: TODO
+== `oidDto`
+The main purpose of the common schema is to define the `oidDto` complex type: the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the
+xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
+Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
+a given Apache Isis application. With it, we have the ability to lookup any arbitrary object. Further discussion and
+examples can be found xref:ug.adoc#_ug_core-concepts_building-blocks_oid[here].
-However, the identity of the underlying entity can be well defined; Apache Isis defines the
-xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
-the object's type and its identifier. This is basically a formal XML equivalent to the `Bookmark` object obtained
-from the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
+
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/common" <!--1-->
+ elementFormDefault="qualified"
+ xmlns="http://isis.apache.org/schema/common"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema">
+ <xs:complexType name="oidDto"> <!--2-->
+ <xs:sequence>
+ <xs:element name="objectType" type="xs:string"/>
+ <xs:element name="objectIdentifier" type="xs:string"/>
+ </xs:sequence>
+ <xs:attribute name="objectState" type="bookmarkObjectState" default="persistent"/>
+ </xs:complexType>
+ <xs:simpleType name="bookmarkObjectState">
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="persistent"/>
+ <xs:enumeration value="transient"/>
+ <xs:enumeration value="viewModel"/>
+ </xs:restriction>
+ </xs:simpleType>
+ ...
+</xs:schema>
+----
+
+This
+
+== `valueDto` and `valueType`
+
+The common schema defines two further types: the `valueDto` complex type and the `valueType` simple type:
+
+[source,xml]
+----
+<xs:schema targetNamespace="http://isis.apache.org/schema/common"
+ elementFormDefault="qualified"
+ xmlns="http://isis.apache.org/schema/common"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema">
+ ...
+ <xs:complexType name="valueDto"> <!--1-->
+ <xs:choice minOccurs="0" maxOccurs="1">
+ <xs:element name="string" type="xs:string"/>
+ <xs:element name="byte" type="xs:byte"/>
+ <xs:element name="short" type="xs:short"/>
+ <xs:element name="int" type="xs:int"/>
+ <xs:element name="long" type="xs:long"/>
+ <xs:element name="float" type="xs:float"/>
+ <xs:element name="double" type="xs:double"/>
+ <xs:element name="boolean" type="xs:boolean"/>
+ <xs:element name="char" type="xs:string"/>
+ <xs:element name="bigDecimal" type="xs:decimal"/>
+ <xs:element name="bigInteger" type="xs:integer"/>
+ <xs:element name="dateTime" type="xs:dateTime"/>
+ <xs:element name="localDate" type="xs:date"/>
+ <xs:element name="localDateTime" type="xs:dateTime"/>
+ <xs:element name="localTime" type="xs:time"/>
+ <xs:element name="reference" type="oidDto"/>
+ </xs:choice>
+ </xs:complexType>
+ <xs:simpleType name="valueType"> <!--2-->
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="string"/>
+ <xs:enumeration value="byte"/>
+ <xs:enumeration value="short"/>
+ <xs:enumeration value="int"/>
+ <xs:enumeration value="long"/>
+ <xs:enumeration value="float"/>
+ <xs:enumeration value="double"/>
+ <xs:enumeration value="boolean"/>
+ <xs:enumeration value="char"/>
+ <xs:enumeration value="bigInteger"/>
+ <xs:enumeration value="bigDecimal"/>
+ <xs:enumeration value="javaUtilDate"/>
+ <xs:enumeration value="javaSqlDate"/>
+ <xs:enumeration value="javaSqlTime"/>
+ <xs:enumeration value="javaSqlTimestamp"/>
+ <xs:enumeration value="jodaDateTime"/>
+ <xs:enumeration value="jodaLocalDate"/>
+ <xs:enumeration value="jodaLocalTime"/>
+ <xs:enumeration value="jodaLocalDateTime"/>
+ <xs:enumeration value="isisApplibBlob"/>
+ <xs:enumeration value="isisApplibClob"/>
+ <xs:enumeration value="reference"/>
+ </xs:restriction>
+ </xs:simpleType>
+</xs:schema>
+----
+
+These two definitions are just building blocks, both used within the xref:rg.adoc#_rg_schema-aim[Action Invocation Memento]
+schema. The first, `valueDto` is intended to hold any valid value, eg of an argument to an action. The second,
+`valueType`, enumerates the different types of vales, eg of a formal parameter to an action.
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
index a696fbf..d5130e1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
@@ -11,4 +11,8 @@ In addition to defining the schemas themselves, Apache Isis also provides some s
`org.apache.isis.schema.utils` package.
-include::_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc[leveloffset=+1]
\ No newline at end of file
+include::_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc[leveloffset=+1]
+
+
+
+PersistentEntityAdapter.class
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
index e8ce6c2..c05e127 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
@@ -5,7 +5,20 @@
:_imagesdir: images/
-NOTE: TODO
+Most applications need to integrate with other apps in the enterprise. To facilitate such integration scenarios,
+Apache Isis defines two standard XSD schemas:
+
+* the xref:rg.adoc#_rg_schema-common[common schema], which defines the `oidDto` complex type: the object's type and its identifier. +
++
+It also defines some two further XSD types, which are building blocks used in...
+
+* the xref:rg.adoc#_rg_schema-aim[action memento invocation] schema, which allows action invocations to be captured
+and reified. +
++
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module uses this XML format
+to publish messages onto an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
+
+The sections below discuss these schemas in more detail.
include::_rg_schema-common.adoc[leveloffset=+1]
include::_rg_schema-aim.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/d409a71a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
index d7c95d0..90e0977 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -7,7 +7,7 @@
In this section we run through the main building blocks that make up an Apache Isis application.
[[_ug_core-concepts_building-blocks_metamodel]]
-## A MetaModel
+== A MetaModel
At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
with optional supporting metadata (eg `Customer.layout.json`).
@@ -41,7 +41,7 @@ sources.
[[_ug_core-concepts_building-blocks_types-of-domain-objects]]
-## Type of Domain Objects
+== Type of Domain Objects
Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and
so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
@@ -208,16 +208,34 @@ in Apache Isis, and do _not_ correspond to actions even though they have public
-## Domain Entities vs View Models
+== Domain Entities vs View Models
-NOTE: TODO
+When developing an Apache Isis application you will most likely start off with the persistent domain entities:
+`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes,
+then you may need to look beyond just domain entities.
+
+To support these use cases we support view models. In the same way that an (RDBMS) database view can aggregate and
+abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
+
+View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain
+entities. Indeed, to a user of the system there is no particular distinction (again, in the same way that when using
+an RDBMS one can use database views and database tables pretty much interchangeably).
+
+View models generally tend to be associated with supporting a particular use case; logically they are part of the
+application layer, not part of the domain layer (where entities live).
+
+We introduce view models here because they do get mentioned quite often within the users and reference guide. However,
+we do consider them a more advanced topic; we generally recommend that you build your applications from the domain
+layer up, rather than from the view model down.
+
+For further discussion on view models, see xref:ug.adoc#_ug_more-advanced_view-models[this topic].
-`@DomainObject(nature=...)`
[[_ug_core-concepts_building-blocks_domain-services]]
-## Domain Services
+== Domain Services
Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
@@ -226,7 +244,7 @@ Domain services are instantiated once and once only by the framework, and are us
For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
-### Domain Services vs View Services
+=== Domain Services vs View Services
NOTE: TODO
@@ -241,27 +259,77 @@ In Apache Isis these are all implemented as domain services. Indeed, it is quit
-
-[[_ug_core-concepts_building-blocks_value-objects]]
-## Value Objects (Primitives)
+[[_ug_core-concepts_building-blocks_mixins-and-contributions]]
+== Mixins & Contributions
NOTE: TODO
+For more information, see xref:ug.adoc#_ug_more-advanced_decoupling_contributions[this topic on contribution]s, and
+xref:ug.adoc#_ug_more-advanced_decoupling_mixins[this topic on mixin]s.
-[[_ug_core-concepts_building-blocks_mixins-and-contributions]]
-## Mixins & Contributions
-NOTE: TODO
+[[_ug_core-concepts_building-blocks_domain-events]]
+== Domain Events
+NOTE: TODO; see xref:rg.adoc#_rg_classes_domainevent[domain event] classes.
+
+
+
+=== UI Events (`1.11.0-SNAPSHOT`)
+
+NOTE: TODO; see xref:rg.adoc#_rg_classes_uievent[UI event] classes.
-[[_ug_core-concepts_building-blocks_domain-events]]
-## Domain Events
-NOTE: TODO
+[[_ug_core-concepts_building-blocks_oid]]
+== OIDs
+
+As well as defining a xref:ug.adoc#_ug_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
+classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+
+When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
+object identifier. Fundamentally this is a combination of its type (domain class), along with an identifier. You can think
+of it as its "primary key", except across all domain entity types.
+
+For portability and resilience, though, the object type is generally an alias for the actual domain class: thus
+"customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer". This is derived from an annotation. The
+identifier meanwhile is always converted to a string.
+
+Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by
+a given Apache Isis application. With it, we have the ability to lookup any arbitrary domain objects.
+
+Some examples:
+
+* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
+
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form. When the PDF is
+scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
+
+* as a handle to any object in an audit record (as used by the
+xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`], in fact).
+
+* and of course both the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] and
+xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]
+use the oid tuple to look up, render and allow the user to interact with domain objects.
+
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
+to obtain OIDs. These are represented as `Bookmark`s, obtained from the
+xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]. Deep links meanwhile can be obtained from
+the xref:rg.adoc#_rg_annotations_manpage-DeepLinkService[`@DeepLinkService`].
+
+OIDs can also be converted into XML format, useful for integration scenarios. The
+xref:rg.adoc#_rg_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+
+
+
+[[_ug_core-concepts_building-blocks_value-objects]]
+== Value Objects (Primitives)
+
+NOTE: TODO
+