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 2017/03/31 07:11:17 UTC
[41/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
deleted file mode 100644
index f782a44..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Column.adoc
+++ /dev/null
@@ -1,154 +0,0 @@
-[[_rgant-Column]]
-= `@Column` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).
-
-Apache Isis also parses and interprets this annotation in order to build up aspects of its metamodel.
-
-[NOTE]
-====
-Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
-This section identifies which attributes of `@Column` are recognized and used by Apache Isis.
-
-
-
-== Nullability
-
-The `allowsNull()` attribute is used to specify if a property is mandatory or is optional.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(allowsNull="true")
- public String getMiddleInitial() { ... }
- public void setMiddleInitial(String middleInitial) { ... }
-----
-
-Isis also provides xref:rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Apache Isis defaults differ. Apache Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.
-
-In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter. But see the documentation for xref:rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
-
-
-
-== Length for ``String``s
-
-The `length()` attribute is used to specify the length of `java.lang.String` property types as they map to `varchar(n)` columns.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=20)
- public String getFirstName() { ... }
- public void setFirstName(String firstName) { ... }
- @javax.jdo.annotations.Column(allowsNull="true", length=1)
- public String getMiddleInitial() { ... }
- public void setMiddleInitial(String middleInitial) { ... }
- @javax.jdo.annotations.Column(length=30)
- public String getLastName() { ... }
- public void setLastName(String lastName) { ... }
-----
-
-Isis also provides xref:rgant.adoc#_rgant-Property_maxLength[`@Property#maxLength()`] attribute. If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
-
-== Length/scale for ``BigDecimal``s
-
-
-The `length()` and `scale()` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=10, scale=2)
- public BigDecimal getTotalOrdersToDate() { ... }
- public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
-----
-
-For ``BigDecimal``s it is also possible to specify the xref:rgant.adoc#_rgant-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`. There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
-
-If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
-
-
-== Hints and Tips
-
-This seems to be a good place to describe some additional common mappings that use `@Column`. Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Apache Isis metamodel.
-
-
-=== Mapping foreign keys
-
-The `name()` attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
-
-For example (taken from link:http://github.com/estatio/estatio[estatio] app):
-
-[source,java]
-----
-public class PartyRelationship {
- @Column(name = "fromPartyId", allowsNull = "false")
- public Party getFrom() { ... }
- public void setFrom(Party from) { ... }
- @Column(name = "toPartyId", allowsNull = "false")
- public Party getTo() { ... }
- public void setTo(Party to) { ... }
- ...
-}
-----
-
-
-
-== Mapping ``Blob``s and ``Clob``s
-
-Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]s. These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database. Mapping this correctly requires using `@Column` within JDO's `@Persistent` annotation.
-
-For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
-
-[source,java]
-----
-private Blob attachment;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "attachment_name"),
- @javax.jdo.annotations.Column(name = "attachment_mimetype"),
- @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "LONGVARBINARY")
-})
-@Property(
- domainEvent = AttachmentDomainEvent.class,
- optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() { ... }
-public void setAttachment(Blob attachment) { ... }
-----
-
-And here's how to map a `Clob` (also taken from the todoapp):
-
-[source,java]
-----
-private Clob doc;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "doc_name"),
- @javax.jdo.annotations.Column(name = "doc_mimetype"),
- @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "LONGVARCHAR")
-})
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() { ... }
-public void setDoc(final Clob doc) { ... }
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Digits.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Digits.adoc
deleted file mode 100644
index 0f28f29..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Digits.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_rgant-Digits]]
-= `@Digits` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `@javax.validation.constraints.Digits` annotation is recognized by Apache Isis as a means to specify the precision for properties and action parameters of type `java.math.BigDecimal`.
-
-For example (taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
-
-[source,java]
-----
-@javax.jdo.annotations.Column(
- scale=2 // <1>
-)
-@javax.validation.constraints.Digits(
- integer=10,
- fraction=2 // <2>
-)
-public BigDecimal getCost() {
- return cost;
-}
-public void setCost(final BigDecimal cost) {
- this.cost = cost!=null
- ? cost.setScale(2, BigDecimal.ROUND_HALF_EVEN) // <3>
- :null;
-}
-----
-<1> the xref:rgant.adoc#_rgant-Column[`@Column#scale()`] attribute must be ...
-<2> ... consistent with `@Digits#fraction()`
-<3> the correct idiom when setting a new value is to normalized to the correct scale
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-Discriminator.adoc
deleted file mode 100644
index 9640dc2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-Discriminator.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_rgant-Discriminator]]
-= `@Discriminator` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.
-
-It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
-
-[NOTE]
-====
-Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
-This value is used internally to generate a string representation of an objects identity (the `Oid`).
-This can appear in several contexts, including:
-
-* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
- ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
-
-
-
-== Examples
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Discriminator(value="custmgmt.Customer")
-public class Customer {
- ...
-}
-----
-
-has an object type of `custmgmt.Customer`.
-
-
-== Precedence
-
-The rules of precedence for determining a domain object's object type are:
-
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
-2. `@DomainObject#objectType`
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined. +
-+
-If both `schema` and `table` are defined, then the value is "`schema.table`".
-If only `schema` is defined, then the value is "`schema.className`".
-
-4. Fully qualified class name of the entity.
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
-
-Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
-====
-
-
-[NOTE]
-====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject.adoc
deleted file mode 100644
index 08e08a9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject.adoc
+++ /dev/null
@@ -1,158 +0,0 @@
-[[_rgant-DomainObject]]
-= `@DomainObject`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `@DomainObject` annotation applies to domain objects, collecting together all domain semantics within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainObject` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:rgant.adoc#_rgant-DomainObject_auditing[`auditing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|indicates whether each of the changed properties of an object should be submitted to the registered
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (deprecated) or (its replacement)
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
-
-
-|xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
-|Domain service class
-|nominate a method on a domain service to be used for looking up instances of the domain object
-
-
-|`autoCompleteAction()`
-|Method name +
-(`autoComplete()`)
-|override the method name to use on the auto-complete repository
-
-
-|xref:rgant.adoc#_rgant-DomainObject_bounded[`bounded()`]
-|`true`, `false` +
-(`false`)
-|Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
-
-|xref:rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`created-` +
-`LifecycleEvent()`]
-|subtype of `ObjectCreatedEvent` +
-(`ObjectCreatedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is created
-
-|xref:rgant.adoc#_rgant-DomainObject_editing[`editing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
-
-
-|xref:rgant.adoc#_rgant-DomainObject_mixinMethod[`mixinMethod()`]
-|Method name within the mixin
-|How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
-Typical examples are "exec", "execute", "invoke", "apply" and so on.
-The default "reserved" method name is `$$`.
-
-
-|xref:rgant.adoc#_rgant-DomainObject_nature[`nature()`]
-|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `MIXIN`, `VIEW_MODEL` (`NOT_SPECIFIED`)
-|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); or is a mixin. If an entity, indicates how its persistence is managed.
-
-
-|xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`]
-|(none, which implies fully qualified class name)
-|specify an alias for the domain class used to uniquely identify the object both within the Apache Isis runtime and externally
-
-
-|xref:rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`persisted-` +
-`LifecycleEvent()`]
-|subtype of `ObjectPersistedEvent` +
-(`ObjectPersistedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been persisted
-
-|xref:rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`persisting-` +
-`LifecycleEvent()`]
-|subtype of `ObjectPersistingEvent` +
-(`ObjectPersistingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be persisted
-
-|xref:rgant.adoc#_rgant-DomainObject_publishing[`publishing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether changes to the object should be published to the registered xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
-
-
-|`publishing-` +
-`PayloadFactory()`
-|subtype of `PublishingPayloadFactory-` `ForObject` (none)
-|specifies that a custom implementation of `PublishingPayloadFactoryForObject` be used to create the (payload of the) published event representing the change to the object
-
-|xref:rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`removing-` +
-`LifecycleEvent()`]
-|subtype of `ObjectRemovingEvent` +
-(`ObjectRemovingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be deleted
-
-|xref:rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`updated-` +
-`LifecycleEvent()`]
-|subtype of `ObjectUpdatedEvent` +
-(`ObjectUpdatedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been updated
-
-|xref:rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`updating-` +
-`LifecycleEvent()`]
-|subtype of `ObjectUpdatingEvent` +
-(`ObjectUpdatingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be updated
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- auditing=Auditing.ENABLED,
- autoCompleteRepository=CustomerRepository.class
- editing=Editing.ENABLED, // <1>
- updatedLifecycleEvent=Customer.UpdatedEvent.class
-
-)
-public class Customer {
- ...
-}
-----
-<1> default value, so could be omitted
-
-
-
-include::_rgant-DomainObject_auditing.adoc[leveloffset=+1]
-include::_rgant-DomainObject_autoCompleteRepository.adoc[leveloffset=+1]
-include::_rgant-DomainObject_bounded.adoc[leveloffset=+1]
-include::_rgant-DomainObject_createdLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_editing.adoc[leveloffset=+1]
-include::_rgant-DomainObject_loadedLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_mixinMethod.adoc[leveloffset=+1]
-include::_rgant-DomainObject_nature.adoc[leveloffset=+1]
-include::_rgant-DomainObject_persistedLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_persistingLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_objectType.adoc[leveloffset=+1]
-include::_rgant-DomainObject_publishing.adoc[leveloffset=+1]
-include::_rgant-DomainObject_removingLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_updatingLifecycleEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObject_updatedLifecycleEvent.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
deleted file mode 100644
index e4fe38a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout.adoc
+++ /dev/null
@@ -1,132 +0,0 @@
-[[_rgant-DomainObjectLayout]]
-= `@DomainObjectLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `@DomainObjectLayout` annotation applies to domain classes, collecting together all UI hints within a single annotation.
-
-
-[NOTE]
-====
-For view models that have been annotated with `@ViewModel` the equivalent xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`] can be used.
-====
-
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainObjectLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`bookmarking()`]
-|`AS_ROOT`, `AS_CHILD`, `NEVER` +
-(`NEVER`)
-|whether (and how) this domain object should be automatically bookmarked
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssclass[`cssClass()`]
-|Any string valid as a CSS class
-|the css class that a domain class (type) should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`cssClassFa()`]
-|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
-|specify a font awesome icon for the action's menu link or icon. +
-
-
-|`cssClassFaPosition()`
-|`LEFT`, `RIGHT` +
-(`LEFT`)
-|Currently unused.
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`]
-|subtype of `CssClassUiEvent` +
-(`CssClassUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain a CSS class for the domain object.
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`describedAs()`]
-|String.
-|description of this class, eg to be rendered in a tooltip.
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`iconUiEvent()`]
-|subtype of `IconUiEvent` +
-(`IconUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the icon (name) for the domain object.
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_named[`named()`]
-|String.
-|to override the name inferred from the action's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_paged[`paged()`]
-|Positive integer
-|the page size for instances of this class when rendered within a table (as returned from an action invocation)
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_plural[`plural()`]
-|String.
-|the plural name of the class
-
-
-|xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`titleUiEvent()`]
-|subtype of `TitleUiEvent` +
-(`TitleUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the title for the domain object.
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- cssClass="x-key",
- cssClassFa="fa-checklist",
- describedAs="Capture a task that you need to do",
- named="ToDo",
- paged=30,
- plural="ToDo List")
-)
-public class ToDoItem {
- ...
-}
-----
-
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-
-
-
-
-include::_rgant-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_cssClassUiEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_iconUiEvent.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_named.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_paged.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_plural.adoc[leveloffset=+1]
-include::_rgant-DomainObjectLayout_titleUiEvent.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_bookmarking.adoc
deleted file mode 100644
index 97dafc6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_bookmarking.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_rgant-DomainObjectLayout_bookmarking]]
-= `bookmarking()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for xref:rgant.adoc#_rgant-Action_bookmarking[domain objects].
-
-(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
-
-image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png"]
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-For example:
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
-public class ToDoItem ... {
- ...
-}
-----
-
-indicates that the `ToDoItem` class is bookmarkable:
-
-
-It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
-
-image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
-
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
-
-This is accomplished with the following annotations:
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
-public class Property { ... }
-----
-
-and
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_CHILD)
-public abstract class Unit { ... }
-----
-
-The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting `Lease` > `LeaseItem` > `LeaseTerm` (3 levels deep).
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
deleted file mode 100644
index 2dbefe6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClass.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_rgant-DomainObjectLayout_cssClass]]
-= `cssClass()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object. xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
-
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- cssClass="x-core-entity"
-)
-public class ToDoItem { ... }
-----
-
-
-
-
-[NOTE]
-====
-The similar xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
-to be rendered as the icon for classes.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
deleted file mode 100644
index ae8c7ef..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_rgant-DomainObjectLayout_cssClassFa]]
-= `cssClassFa()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
-
-These attributes can also be applied to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
-
-If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- cssClassFa="fa-check-circle"
-)
-public class ToDoItem { ... }
-----
-
-There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list. The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
-
-
-The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
-
-
-[TIP]
-====
-The similar xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
-to apply CSS, but for wrapping the representation of an object or object
-member so that it can be styled in an application-specific way.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
deleted file mode 100644
index 2cf1881..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-[[_rgant-DomainObjectLayout_cssClassUiEvent]]
-= cssClassUiEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
-in any wrapping ``<div>``s and ``<span>``s that render the domain object. This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] reserved method. (If `cssClass()` is present, then
-it will take precedence).
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use obtain a reference to the domain object from the event. From this they can, if they wish, specify a CSS class for
-the domain object using the event's API.
-
-[NOTE]
-====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
-====
-
-By default the event raised is `CssClassUiEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `cssClassUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for titles and icons.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- iconUiEvent=ToDoItemDto.CssClassUiEvent.class
-)
-public class ToDoItemDto {
- public static class CssClassUiEvent
- extends org.apache.isis.applib.services.eventbus.CssClassUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
-using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(CssClassUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItemDto.CssClassUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use `CssClassUiEvent#setCssClass(...)` to actually specify the CSS class to be used.
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `cssClassUiEvent` attribute is not explicitly specified (is left as its default value, `CssClassUiEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.cssClassUiEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `cssClassUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `CssClassUiEvent.Doop` as such a subclass, so setting the `cssClassUiEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `CssClassUiEvent.Noop`; if `cssClassUiEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
-`cssClassOf(...)` method.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_describedAs.adoc
deleted file mode 100644
index e978830..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_describedAs.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_rgant-DomainObjectLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `describedAs()` attribute is used to provide a short description of the domain object to the user. In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
-
-For example:
-
-[source,java]
-----
-@DescribedAs("A customer who may have originally become known to us via " +
- "the marketing system or who may have contacted us directly.")
-public class ProspectiveSale {
- ...
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
deleted file mode 100644
index 5c077e1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ /dev/null
@@ -1,122 +0,0 @@
-[[_rgant-DomainObjectLayout_iconUiEvent]]
-= iconUiEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
-object (if possible). This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] reserved method. (If `iconName()` is present, then
-it will take precedence).
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use obtain a reference to the domain object from the event. From this they can, if they wish, specify an icon name for
-the domain object using the event's API.
-
-
-[NOTE]
-====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
-====
-
-By default the event raised is `IconUiEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `iconUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for titles and CSS classes.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- iconUiEvent=ToDoItemDto.IconUiEvent.class
-)
-public class ToDoItemDto {
- public static class IconUiEvent
- extends org.apache.isis.applib.services.eventbus.IconUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
-using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(IconUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItemDto.IconUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use `IconUiEvent#setIconName(...)` to actually specify the icon name to be used.
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-== Default, Doop and Noop events
-
-If the `iconUiEvent` attribute is not explicitly specified (is left as its default value, `IconUiEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.iconUiEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `iconUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `iconUiEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
-`iconNameOf(...)` method.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_named.adoc
deleted file mode 100644
index dc178ab..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_named.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgant-DomainObjectLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
-
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- named="Customer"
-)
-public class CustomerImpl implements Customer{
- ...
-}
-----
-
-It's also possible to specify a xref:rgant.adoc#_rgant-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
deleted file mode 100644
index 17921a8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_paged.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_rgant-DomainObjectLayout_paged]]
-= `paged()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:rgant.adoc#_rgant-ViewModelLayout_paged[view models].
-
-
-[WARNING]
-====
-The xref:ugvro.adoc#[RestfulObjects viewer] currently does not support paging. The xref:ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
-
-We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
-====
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(paged=15)
-public class Order {
- ...
-}
-----
-
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_plural.adoc
deleted file mode 100644
index 8c57f27..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_plural.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_rgant-DomainObjectLayout_plural]]
-= `plural()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
-
-By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-
-The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:rgant.adoc#_rgant-ViewModelLayout_plural[view models].
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(plural="Children")
-public class Child {
- ...
-}
-----
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
deleted file mode 100644
index af87cd4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ /dev/null
@@ -1,120 +0,0 @@
-[[_rgant-DomainObjectLayout_titleUiEvent]]
-= titleUiEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or
-using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself. (If either
-`title()` or `@Title` are present, then they will take precedence).
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use obtain a reference to the domain object from the event. From this they can, if they wish, specify a title for
-the domain object using the event's API.
-
-[NOTE]
-====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
-====
-
-By default the event raised is `TitleUiEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObjectLayout
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `titleUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for icon names and CSS classes.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- titleUiEvent=ToDoItemDto.TitleUiEvent.class
-)
-public class ToDoItemDto {
- public static class TitleUiEvent
- extends org.apache.isis.applib.services.eventbus.TitleUiEvent<ToDoItemDto> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
-using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(TitleUiEvent ev) {
- if(ev.getSource() instanceof ToDoItemDto) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItemDto.TitleUiEvent ev) {
- ...
- }
-}
-----
-
-The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to
-actually specify the title to be used.
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-== Default, Doop and Noop events
-
-If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `titleUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `titleUiEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class,
-thn no event will be posted.
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
-`titleOf(...)` method.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
deleted file mode 100644
index 6b54c3a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_auditing.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_rgant-DomainObject_auditing]]
-= `auditing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-The `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be
-submitted to the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (if one has been configured), or to
-any
-
-The default value for the attribute is `AS_CONFIGURED`, meaning that the
-xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the
-whether the action is audited:
-
-* `all` +
-+
-all changed properties of objects are audited
-
-* `none` +
-+
-no changed properties of objects are audited
-
-If there is no configuration property in `isis.properties` then auditing is automatically enabled for domain objects.
-
-This default can be overridden on an object-by-object basis; if `auditing()` is set to `ENABLED` then changed
-properties of instances of the domain class are audited irrespective of the configured value; if set to `DISABLED` then
-the changed properties of instances are _not_ audited, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- auditing=Auditing.ENABLED // <1>
-)
-public class Customer {
- ...
-}
-----
-<1> because set to enabled, will be audited irrespective of the configured value.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
deleted file mode 100644
index 5719056..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_autoCompleteRepository.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_rgant-DomainObject_autoCompleteRepository]]
-= `autoCompleteRepository()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `autoCompleteRepository()` attribute nominates a single method on a domain service as the fallback means for
-looking up instances of the domain object using a simple string.
-
-For example, this might search for a customer by their name or number. Or it could search for a country based on its ISO-3 code or user-friendly name.
-
-
-[TIP]
-====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method instead.
-====
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- autoCompleteRepository=CustomerRepository.class
-)
-public class Customer {
- ....
-}
-----
-
-where:
-
-[source,java]
-----
-@DomainService
-public class CustomerRepository {
- List<Customer> autoComplete(String search); // <1>
- ...
-}
-----
-<1> is assumed to be called "autoComplete", and accepts a single string
-
-
-
-== `autoCompleteAction()`
-
-As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional `autoCompleteAction()` attribute allows the method on the repository to be overridden.
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- autoCompleteRepository=Customers.class,
- autoCompleteAction="findByName"
-)
-public class Customer {
- ....
-}
-----
-
-where in this case `findByName` might be an existing action already defined:
-
-[source,java]
-----
-@DomainService(natureOfService=VIEW_MENU_ONLY)
-public class Customers {
- @Action(semantics=SemanticsOf.SAFE)
- public List<Customer> findByName(
- @Parameter(minLength=3) // <1>
- @ParameterLayout(named="name")
- String name);
- ...
-}
-----
-<1> end-user must enter minimum number of characters to trigger the query
-
-The autocomplete action can also be a regular method, annotated using xref:rgant.adoc#_rgant_Programmatic[`@Programmatic`]:
-
-[source,java]
-----
-@DomainService(natureOfService=VIEW_MENU_ONLY)
-public class Customers {
- @Programmatic
- public List<Customer> findByName(
- @Parameter(minLength=3)
- String name);
- ...
-}
-----
-
-
-[IMPORTANT]
-====
-The method specified must be an action, that is, part of the Isis metamodel. Said another way: it must not be annotated with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]. However, it *can* be hidden or placed on a domain service with xref:rgant.adoc#_rgant-DomainService_nature[nature] of `DOMAIN`, such that the action would not be rendered otherwise in the UI. Also, the action cannot be xref:rgant.adoc#_rgant-Action_restrictTo[restricted to] prototyping only.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
deleted file mode 100644
index d0f4de6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_bounded.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_rgant-DomainObject_bounded]]
-= `bounded()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Some domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.
-
-Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint. For such domain objects the framework will automatically allow instances to be selected; xref:ugvw.adoc#[Wicket viewer] displays these as a drop-down list.
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- bounded=true,
- editing=Editing.DISABLED // <1>
-)
-public class Currency {
- ...
-}
-----
-<1> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
-
-
-[TIP]
-====
-There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping. However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_createdLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_createdLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_createdLifecycleEvent.adoc
deleted file mode 100644
index a19bd87..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_createdLifecycleEvent.adoc
+++ /dev/null
@@ -1,108 +0,0 @@
-[[_rgant-DomainObject_createdLifecycleEvent]]
-= createdLifecycleEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired. This is typically when the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`newTransientInstance()`] is called;
-it will also happen if the object is simply instantiated with `new(...)`, and then the container's
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_services-api[`injectServicesInto(...)`] method is called.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the object just created. The subscriber could then, for example, update the
-object, eg looking up state from some external datastore.
-
-
-By default the event raised is `ObjectCreatedEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `createdLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- createdLifecycleEvent=ToDoItem.CreatedEvent.class
-)
-public class ToDoItem {
- public static class CreatedEvent
- extends org.apache.isis.applib.services.eventbus.ObjectCreatedEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
-using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectCreatedEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectCreatedEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `createdLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectCreatedEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.createdLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `createdLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectCreatedEvent.Doop` as such a subclass, so setting the `createdLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectCreatedEvent.Noop`; if `createdLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
deleted file mode 100644
index 6a15cfa..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_editing.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_rgant-DomainObject_editing]]
-= `editing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only).
-
-The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
-
-* `true` +
-+
-the object's properties and collections are modifiable.
-
-* `false` +
-+
-the object's properties and collections are read-only, ie _not_ modifiable.
-
-If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
-
-[TIP]
-====
-In other words, editing can be disabled globally for an application by setting:
-
-[source,ini]
-----
-isis.objects.editing=false
-----
-
-We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
-====
-
-The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
-
-
-
-This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- editing=Editing.DISABLED,
- editingDisabledReason="Reference data, so cannot be modified"
-)
-public class Country {
- ...
-}
-----
-
-[TIP]
-====
-Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_loadedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_loadedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_loadedLifecycleEvent.adoc
deleted file mode 100644
index b33d688..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_loadedLifecycleEvent.adoc
+++ /dev/null
@@ -1,105 +0,0 @@
-[[_rgant-DomainObject_loadedLifecycleEvent]]
-= loadedLifecycleEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a persistent domain object is loaded from the database, a "loaded" lifecycle event is fired.
-
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object just loaded. The subscriber could then, for example, update
-or default values on the object (eg to support on-the-fly migration scenarios).
-
-By default the event raised is `ObjectLoadedEvent.Default`. For example:
-
-[source,java]
-----
-@DomainObject
-public class ToDoItemDto {
- ...
-}
-----
-
-The purpose of the `loadedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- loadedLifecycleEvent=ToDoItem.LoadedEvent.class
-)
-public class ToDoItem {
- public static class LoadedEvent
- extends org.apache.isis.applib.services.eventbus.ObjectLoadedEvent<ToDoItem> { }
- ...
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
-using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ObjectLoadedEvent ev) {
- if(ev.getSource() instanceof ToDoItem) { ... }
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.ObjectLoadedEvent ev) {
- ...
- }
-}
-----
-
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-
-
-
-== Default, Doop and Noop events
-
-If the `loadedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectLoadedEvent.Default`),
-then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.loadedLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `loadedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectLoadedEvent.Doop` as such a subclass, so setting the `loadedLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ObjectLoadedEvent.Noop`; if `loadedLifecycleEvent` attribute is set to this class,
-then no event will be posted.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_mixinMethod.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_mixinMethod.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_mixinMethod.adoc
deleted file mode 100644
index 7a82f19..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-DomainObject_mixinMethod.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_rgant-DomainObject_mixinMethod]]
-= `mixinMethod()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The `mixinMethod()` attribute specifies the name of the method to be treated as a "reserved" method name, meaning that the mixin's name should instead be inferred from the mixin's type.
-
-For example:
-
-[source,java]
-----
-@DomainObject
-public class Customer {
-
- @DomainObject(nature=Nature.MIXIN, mixinMethod="execute")
- public static class placeOrder {
-
- Customer customer;
- public placeOrder(Customer customer) { this.customer = customer; }
-
- public Customer execute(Product p, int quantity) { ... }
- public String disableExecute() { ... }
- public String validate0Execute() { ... }
- }
- ...
-)
-----
-
-This allows all mixins to follow a similar convention, with the name of the mixin inferred entirely from its type ("placeOrder").
-
-When invoked programmatically, the code reads:
-
-[source,java]
-----
-mixin(Customer.placeOrder.class, someCustomer).execute(someProduct, 3);
-----
-