You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 15:31:20 UTC
[13/52] [abbrv] isis git commit: ISIS-1243: removing manpage from
.adoc file names.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
deleted file mode 100644
index 73cce6d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-hide.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-hide]]
-= `hide...()`
-: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 `hide...()` supporting method is called for properties, collections and actions. It allows the property/collection to be completely hidden from view.
-
-It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[disabled], ie greyed out).
-
-
-== Actions
-
-For an action the signature of the supporting method is either:
-
-[source,java]
-----
-public bool hideXxx(...) { ... }
-----
-
-where the supporting method takes the same parameter types as the action itself, or more simply:
-
-[source,java]
-----
-public bool hideXxx() { ... }
-----
-
-with no parameters at all. Returning `true` will hide the action, returning `false` leaves it visible.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public boolean isBlacklisted() { ... }
-
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named="Quantity")
- final int quantity) {
- ...
- }
- public boolean hidePlaceOrder() {
- return isBlacklisted();
- }
- ...
-}
-----
-
-
-
-== Properties and Collections
-
-For both properties and collections the signature of the supporting method is:
-
-[source,java]
-----
-public boolean hideXxx() { ... }
-----
-
-where returning `true` will hide the property/collection, returning `false` leaves it visible.
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public boolean isBlacklisted() { ... }
-
- public BigDecimal getCreditLimit() { ... }
- public void setCreditLimit(BigDecimal creditLimit) { ... }
- public boolean hideCreditLimit() {
- return isBlacklisted();
- }
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
deleted file mode 100644
index faee86d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-modify.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-modify]]
-= `modify...()`
-: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 `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value. Its purpose is to allow additional business logic to be performed.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
- public Title getFavoriteTitle() { ... }
- public void setFavoriteTitle(Title title) { ... }
- public void modifyFavoriteTitle(Title title) {
- if(getTitle() != null) {
- titleFavoritesService.decrement(getTitle()); // <1>
- }
- setFavoriteTitle(title); // <2>
- titleFavoritesService.decrement(title); // <3>
- }
- public void clearFavoriteTitle() { ... }
- ...
-}
-----
-<1> perform some additional business logic
-<2> update the property
-<3> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-clear[`clear...()`]`
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
deleted file mode 100644
index 88ef934..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-removeFrom.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-removeFrom]]
-= `removeFrom...()`
-: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 `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
-====
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
- public SortedSet<Book> getBorrowed() { ... }
- public void setBorrowed(SortedSet<Book> borrowed) { ... }
- public void addToBorrowed(Book book) { ... }
- public void removeFromBorrowed(Book book) {
- getBorrowed().remove(book); // <1>
- reminderService.removeReminder(this, book); // <2>
- }
- ...
-}
-----
-<1> update the collection
-<2> perform some additional business logic
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`]`
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
deleted file mode 100644
index 03d9f0d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-set.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-set]]
-= `set...()`
-: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 `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-get[`get...()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
deleted file mode 100644
index 74ccf58..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validate.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validate]]
-= `validate...()`
-: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 `validate...()` supporting method is called for properties, actions and action parameters. It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
-
-
-The reason for vetoing a modification/invocation is normally returned as a string. However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-
-== Action Parameter
-
-For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
-
-[source,java]
-----
-public String validateNXxx(T proposed) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named="Quantity")
- final int quantity) {
- ...
- }
- public String validate0PlaceOrder(
- final Product product) {
- return product.isDiscontinued()
- ? "Product has been discontinued"
- : null;
- }
- ...
-}
-----
-
-
-== Action Parameter Set
-
-In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments. The signature is:
-
-[source,java]
-----
-public String validateXxx(...) { ... }
-----
-
-where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named="Quantity")
- final int quantity) {
- ...
- }
- public String validatePlaceOrder(
- final Product product,
- final int quantity) {
- return quantity > product.getOrderLimit()
- ? "May not order more than " + product.getOrderLimit() + " items for this product"
- : null;
- }
- ...
-}
-----
-
-
-
-== Properties
-
-For properties of type `T` the signature of the supporting method is:
-
-[source,java]
-----
-public String validateXxx(T proposed) { ... }
-----
-
-where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public BigDecimal getCreditLimit() { ... }
- public void setCreditLimit(BigDecimal creditLimit) { ... }
- public validateCreditLimit(BigDecimal creditLimit) {
- return creditLimit.compareTo(BigDecimal.ZERO) < 0
- ? "Credit limit cannot be negative"
- : null;
- }
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
deleted file mode 100644
index 3458533..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateAddTo.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validateAddTo]]
-= `validateAddTo...()`
-: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 `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateAddToXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed). Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
- public SortedSet<Book> getBorrowed() { ... }
- public void setBorrowed(SortedSet<Book> borrowed) { ... }
- public String validateAddToBorrowed(Book book) {
- return book.isReference()? "Reference books cannot be borrowed": null;
- }
- public void validateRemoveFromBorrowed(Book book) { ... }
- ...
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-addTo[`addTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`]`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
deleted file mode 100644
index dbb9979..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_manpage-validateRemoveFrom.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_rgcms_methods_prefixes_manpage-validateRemoveFrom]]
-= `validateRemoveFrom...()`
-: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 `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
-
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
-====
-
-
-The signature of the supporting method for a collection with element type `E` is:
-
-[source,java]
-----
-public String validateRemoveFromXxx(E element) { ... }
-----
-
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed). Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
-
-
-For example:
-
-[source,java]
-----
-public class LibraryMember {
- public SortedSet<Book> getBorrowed() { ... }
- public void setBorrowed(SortedSet<Book> borrowed) { ... }
- public String validateAddToBorrowed(Book book) { ... }
- public void validateRemoveFromBorrowed(Book book) {
- return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
- }
- ...
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-removeFrom[`removeFrom...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-validateAddTo[`validateAddTo...()`]`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
new file mode 100644
index 0000000..5920687
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_modify.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_modify]]
+= `modify...()`
+: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 `modify...()` supporting method is called -- instead of the setter -- whenever a property has been set to be set to a new value. Its purpose is to allow additional business logic to be performed.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+ public Title getFavoriteTitle() { ... }
+ public void setFavoriteTitle(Title title) { ... }
+ public void modifyFavoriteTitle(Title title) {
+ if(getTitle() != null) {
+ titleFavoritesService.decrement(getTitle()); // <1>
+ }
+ setFavoriteTitle(title); // <2>
+ titleFavoritesService.decrement(title); // <3>
+ }
+ public void clearFavoriteTitle() { ... }
+ ...
+}
+----
+<1> perform some additional business logic
+<2> update the property
+<3> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
new file mode 100644
index 0000000..ecf499c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_removeFrom.adoc
@@ -0,0 +1,37 @@
+[[_rgcms_methods_prefixes_removeFrom]]
+= `removeFrom...()`
+: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 `removeFrom...()` supporting method is called whenever an object is removed from a collection. Its purpose is to allow additional business logic to be performed.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
+====
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+ public SortedSet<Book> getBorrowed() { ... }
+ public void setBorrowed(SortedSet<Book> borrowed) { ... }
+ public void addToBorrowed(Book book) { ... }
+ public void removeFromBorrowed(Book book) {
+ getBorrowed().remove(book); // <1>
+ reminderService.removeReminder(this, book); // <2>
+ }
+ ...
+}
+----
+<1> update the collection
+<2> perform some additional business logic
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
new file mode 100644
index 0000000..4135bf1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_set.adoc
@@ -0,0 +1,13 @@
+[[_rgcms_methods_prefixes_set]]
+= `set...()`
+: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 `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
new file mode 100644
index 0000000..4c85cf9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validate.adoc
@@ -0,0 +1,113 @@
+[[_rgcms_methods_prefixes_validate]]
+= `validate...()`
+: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 `validate...()` supporting method is called for properties, actions and action parameters. It allows the proposed new value for a property to be rejected, or the proposed argument of an action parameter to be rejected, or to reject a whole set of action arguments for an actio invocation.
+
+
+The reason for vetoing a modification/invocation is normally returned as a string. However, Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+
+== Action Parameter
+
+For an action parameter in (0-based) position _N_, and of type `T`, the signature is:
+
+[source,java]
+----
+public String validateNXxx(T proposed) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed).
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product,
+ @ParameterLayout(named="Quantity")
+ final int quantity) {
+ ...
+ }
+ public String validate0PlaceOrder(
+ final Product product) {
+ return product.isDiscontinued()
+ ? "Product has been discontinued"
+ : null;
+ }
+ ...
+}
+----
+
+
+== Action Parameter Set
+
+In addition to validating a single single action argument, it is also possible to validate a complete set of action arguments. The signature is:
+
+[source,java]
+----
+public String validateXxx(...) { ... }
+----
+
+where the returned string is the reason why the argument is rejected (or `null` if not vetoed), and the supporting method takes the same parameter types as the action itself.
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product,
+ @ParameterLayout(named="Quantity")
+ final int quantity) {
+ ...
+ }
+ public String validatePlaceOrder(
+ final Product product,
+ final int quantity) {
+ return quantity > product.getOrderLimit()
+ ? "May not order more than " + product.getOrderLimit() + " items for this product"
+ : null;
+ }
+ ...
+}
+----
+
+
+
+== Properties
+
+For properties of type `T` the signature of the supporting method is:
+
+[source,java]
+----
+public String validateXxx(T proposed) { ... }
+----
+
+where the returned string is the reason the modification is vetoed (or `null` if not vetoed).
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public BigDecimal getCreditLimit() { ... }
+ public void setCreditLimit(BigDecimal creditLimit) { ... }
+ public validateCreditLimit(BigDecimal creditLimit) {
+ return creditLimit.compareTo(BigDecimal.ZERO) < 0
+ ? "Credit limit cannot be negative"
+ : null;
+ }
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
new file mode 100644
index 0000000..5b1f535
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateAddTo.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_validateAddTo]]
+= `validateAddTo...()`
+: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 `validateAddTo...()` supporting method is called whenever an object is to be added to a collection. Its purpose is to validate the proposed object and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateAddToXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed). Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+ public SortedSet<Book> getBorrowed() { ... }
+ public void setBorrowed(SortedSet<Book> borrowed) { ... }
+ public String validateAddToBorrowed(Book book) {
+ return book.isReference()? "Reference books cannot be borrowed": null;
+ }
+ public void validateRemoveFromBorrowed(Book book) { ... }
+ ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`]`
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
new file mode 100644
index 0000000..773b269
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_prefixes_validateRemoveFrom.adoc
@@ -0,0 +1,45 @@
+[[_rgcms_methods_prefixes_validateRemoveFrom]]
+= `validateRemoveFrom...()`
+: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 `validateRemoveFrom...()` supporting method is called whenever an object is to be removed from a collection. Its purpose is to validate the proposed object removal and possibly veto the change.
+
+
+[NOTE]
+====
+Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]. The suggested workaround is to simply define an action.
+====
+
+
+The signature of the supporting method for a collection with element type `E` is:
+
+[source,java]
+----
+public String validateRemoveFromXxx(E element) { ... }
+----
+
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed). Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that reasons can be internationalized if required.
+
+
+For example:
+
+[source,java]
+----
+public class LibraryMember {
+ public SortedSet<Book> getBorrowed() { ... }
+ public void setBorrowed(SortedSet<Book> borrowed) { ... }
+ public String validateAddToBorrowed(Book book) { ... }
+ public void validateRemoveFromBorrowed(Book book) {
+ return !book.hasBeenReadBy(this)? "You didn't read this book yet": null;
+ }
+ ...
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`]`
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
index bae5286..e405888 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved.adoc
@@ -15,33 +15,33 @@ The table below lists the reserved methods that are recognized as part of Apache
|Method
|Description
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
|Provides a CSS class for this object instance. In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable(...)`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable(...)`]
|Disable all or some of an object's properties
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-getId[`getId()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
|Provides an optional unique identifier of a service. +
If not provided, the service's fully-qualified class name is used.
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide(...)`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide(...)`]
|Hide all or some of an object's properties
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`]
|Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
|Provides a title for the object. +
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
+See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
-|xref:rgcms.adoc#_rgcms_methods_reserved_manpage-validate[`validate()`]
+|xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
|Validate the object's state prior to persisting.
|===
@@ -49,10 +49,10 @@ See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`]
-include::_rgcms_methods_reserved_manpage-cssClass.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-disable.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-getId.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-hide.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-iconName.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-title.adoc[leveloffset=+1]
-include::_rgcms_methods_reserved_manpage-validate.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_cssClass.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_disable.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_getId.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_hide.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_iconName.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_title.adoc[leveloffset=+1]
+include::_rgcms_methods_reserved_validate.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
new file mode 100644
index 0000000..9e98b39
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_cssClass.adoc
@@ -0,0 +1,46 @@
+[[_rgcms_methods_reserved_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()` returns a CSS class for a particular object instance.
+
+The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added. This is done both for rendering the object either in a table or when rendering the object on its own page.
+
+In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items. This is shown on the home page:
+
+image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public String cssClass() {
+ return !isComplete() ? "todo" : "done";
+ }
+ ...
+}
+----
+
+In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
+
+[source,css]
+----
+tr.todo {
+}
+tr.done {
+ text-decoration: line-through;
+ color: #d3d3d3;
+}
+----
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
new file mode 100644
index 0000000..0490c73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_disable.adoc
@@ -0,0 +1,102 @@
+[[_rgcms_methods_reserved_disable]]
+= `disable()`
+: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/
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
+
+It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+
+For example:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) {
+ return !calendarService.isOfficeHours(clock.today()
+ ? "Cannot modify objects outside of office hours"
+ : null;
+}
+----
+
+See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`. A good pattern is to make these nested static classes. For example:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public static abstract class PropertyDomainEvent<T>
+ extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
+ ...
+ }
+ ...
+}
+----
+
+where in turn:
+
+[source,java]
+----
+public final class ToDoAppDomainModule {
+ private ToDoAppDomainModule(){}
+ public abstract static class PropertyDomainEvent<S,T>
+ extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
+ ...
+ }
+ ...
+}
+----
+
+Then, each property/collection/action emits either these base domain events or their own subclass:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public static class DescriptionDomainEvent
+ extends PropertyDomainEvent<String> {
+ ...
+ }
+ @Property(
+ domainEvent = DescriptionDomainEvent.class
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+A vetoing subscriber can then subscribe to the domain events and veto access, eg:
+
+[source,java]
+----
+@DomainObject
+public class VetoOutOfOfficeHours {
+ @Subscribe
+ public void on(ToDoItem.PropertyDomainEvent ev) {
+ if(!calendarService.isOfficeHours(clock.today()) {
+ ev.veto("Cannot modify objects outside of office hours");
+ }
+ }
+ ...
+}
+----
+
+Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
new file mode 100644
index 0000000..3c37320
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_getId.adoc
@@ -0,0 +1,19 @@
+[[_rgcms_methods_reserved_getId]]
+= `getId()`
+: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 `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
+
+This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
+
+If the identifier is omitted, the services fully qualified class name is used.
+
+[TIP]
+====
+Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services. The principle benefit is shorter URLs in the REST API.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
new file mode 100644
index 0000000..0ee32e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_hide.adoc
@@ -0,0 +1,39 @@
+[[_rgcms_methods_reserved_hide]]
+= `hide()`
+: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/
+
+
+
+One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden. For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
+
+While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] method for each and every action, this could become painful. So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+For example:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) {
+ return identifierType == Identifier.Type.ACTION && isFrozen();
+}
+----
+
+See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_disable[here].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
new file mode 100644
index 0000000..b9e74b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_iconName.adoc
@@ -0,0 +1,36 @@
+[[_rgcms_methods_reserved_iconName]]
+= `iconName()`
+: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/
+
+
+Every object is represented by an icon; this is based on the domain object's simple name. The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
+
+The `iconName()` allows the icon that to be used to change for individual object instances. These are usually quite subtle, for example to reflect the particular status of an object. The value returned by the `iconName()` method is added as a suffix to the base icon name.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
+
+
+
+The screenshot below shows the location of these png icon files:
+
+image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
+
+
+
+The code to accomplish this is straightforward:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public String iconName() {
+ return !isComplete() ? "todo" : "done";
+ }
+ ...
+}
+----
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
deleted file mode 100644
index ecf7f39..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-cssClass.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_rgcms_methods_reserved_manpage-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()` returns a CSS class for a particular object instance.
-
-The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added. This is done both for rendering the object either in a table or when rendering the object on its own page.
-
-In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items. This is shown on the home page:
-
-image::{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png[width="800px",link="{_imagesdir}reference-methods/reserved/cssClass/strikethrough.png"]
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
- public String cssClass() {
- return !isComplete() ? "todo" : "done";
- }
- ...
-}
-----
-
-In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
-
-[source,css]
-----
-tr.todo {
-}
-tr.done {
- text-decoration: line-through;
- color: #d3d3d3;
-}
-----
-
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
deleted file mode 100644
index a56b684..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-disable.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_rgcms_methods_reserved_manpage-disable]]
-= `disable()`
-: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/
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
-
-It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
-
-For example:
-
-[source,java]
-----
-public String disable(Identifier.Type identifierType) {
- return !calendarService.isOfficeHours(clock.today()
- ? "Cannot modify objects outside of office hours"
- : null;
-}
-----
-
-See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-hide[`hide()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`. A good pattern is to make these nested static classes. For example:
-
-[source,java]
-----
-public class ToDoItem ... {
- public static abstract class PropertyDomainEvent<T>
- extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
- ...
- }
- ...
-}
-----
-
-where in turn:
-
-[source,java]
-----
-public final class ToDoAppDomainModule {
- private ToDoAppDomainModule(){}
- public abstract static class PropertyDomainEvent<S,T>
- extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
- ...
- }
- ...
-}
-----
-
-Then, each property/collection/action emits either these base domain events or their own subclass:
-
-[source,java]
-----
-public class ToDoItem ... {
- public static class DescriptionDomainEvent
- extends PropertyDomainEvent<String> {
- ...
- }
- @Property(
- domainEvent = DescriptionDomainEvent.class
- )
- public String getDescription() { ... }
- ...
-}
-----
-
-A vetoing subscriber can then subscribe to the domain events and veto access, eg:
-
-[source,java]
-----
-@DomainObject
-public class VetoOutOfOfficeHours {
- @Subscribe
- public void on(ToDoItem.PropertyDomainEvent ev) {
- if(!calendarService.isOfficeHours(clock.today()) {
- ev.veto("Cannot modify objects outside of office hours");
- }
- }
- ...
-}
-----
-
-Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
deleted file mode 100644
index e2a46ea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-getId.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_rgcms_methods_reserved_manpage-getId]]
-= `getId()`
-: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 `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
-
-This identifier corresponds in many ways to the xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ugvro.adoc#[RestfulObjects viewer]'s REST API.
-
-If the identifier is omitted, the services fully qualified class name is used.
-
-[TIP]
-====
-Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services. The principle benefit is shorter URLs in the REST API.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
deleted file mode 100644
index c069657..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-hide.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_rgcms_methods_reserved_manpage-hide]]
-= `hide()`
-: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/
-
-
-
-One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden. For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
-
-While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-hide[`hide...()`] method for each and every action, this could become painful. So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
-
-The signature of the method is:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) { ... }
-----
-
-where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
-
-For example:
-
-[source,java]
-----
-public boolean hide(Identifier.Type identifierType) {
- return identifierType == Identifier.Type.ACTION && isFrozen();
-}
-----
-
-See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[`disable()`] object members en-masse.
-
-
-== Alternatives
-
-An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
-
-There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_manpage-disable[here].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
deleted file mode 100644
index 049151b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-iconName.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_rgcms_methods_reserved_manpage-iconName]]
-= `iconName()`
-: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/
-
-
-Every object is represented by an icon; this is based on the domain object's simple name. The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object.
-
-The `iconName()` allows the icon that to be used to change for individual object instances. These are usually quite subtle, for example to reflect the particular status of an object. The value returned by the `iconName()` method is added as a suffix to the base icon name.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-image::{_imagesdir}reference-methods/reserved/iconName/differing.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/differing.png"]
-
-
-
-The screenshot below shows the location of these png icon files:
-
-image::{_imagesdir}reference-methods/reserved/iconName/png-files.png[width="200px",link="{_imagesdir}reference-methods/reserved/iconName/png-files.png"]
-
-
-
-The code to accomplish this is straightforward:
-
-[source,java]
-----
-public class ToDoItem ... {
- public String iconName() {
- return !isComplete() ? "todo" : "done";
- }
- ...
-}
-----
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
deleted file mode 100644
index 394c9f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-title.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_rgcms_methods_reserved_manpage-title]]
-= `title()`
-: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/
-
-
-
-Every object is represented by a title. This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections. It therefore must contain enough information for the end-user to distinguish the object from any others.
-
-This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth. However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
-
-An object's title can be constructed in various ways, but the most flexible is to use the `title()` method. The signature of this method is usually:
-
-[source,java]
-----
-public String title() { ... }
-----
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
-
-[source,java]
-----
-public String title() {
- final TitleBuffer buf = new TitleBuffer(); // <1>
- buf.append(getDescription());
- if (isComplete()) { // <2>
- buf.append("- Completed!");
- } else {
- try {
- final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy(); // <3>
- if (dueBy != null) {
- buf.append(" due by", dueBy);
- }
- } catch(final HiddenException ignored) { // <4>
- }
- }
- return buf.toString();
-}
-----
-<1> simple xref:rgcms.adoc#_rgcms_classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
-<2> imperative conditional logic
-<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
-<4> ... but ignore if not
-
-As the example above shows, the implementation can be as complex as you like.
-
-In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
-
-
-See also xref:rgcms.adoc#_rgcms_methods_reserved_manpage-iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_manpage-cssClass[`cssClass()`]
-
-
-
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
deleted file mode 100644
index 24c83f9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_manpage-validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rgcms_methods_reserved_manpage-validate]]
-= `validate()`
-: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 `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-
-
-[WARNING]
-====
-(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
-====
-
-
-The signature of the method is:
-
-[source,java]
-----
-public String validate() { ... }
-----
-
-where the returned string is the reason that the invocation is vetoed.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
new file mode 100644
index 0000000..4a97ea5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_title.adoc
@@ -0,0 +1,65 @@
+[[_rgcms_methods_reserved_title]]
+= `title()`
+: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/
+
+
+
+Every object is represented by a title. This appears both as a main header for the object when viewed as well as being used as a hyperlink within properties and collections. It therefore must contain enough information for the end-user to distinguish the object from any others.
+
+This is most commonly done by including some unique key within the title, for example a customer's SSN, or an order number, and so forth. However note that Apache Isis itself does _not_ require the title to be unique; it is merely recommended in most cases.
+
+An object's title can be constructed in various ways, but the most flexible is to use the `title()` method. The signature of this method is usually:
+
+[source,java]
+----
+public String title() { ... }
+----
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that titles can also be internationalized.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
+
+[source,java]
+----
+public String title() {
+ final TitleBuffer buf = new TitleBuffer(); // <1>
+ buf.append(getDescription());
+ if (isComplete()) { // <2>
+ buf.append("- Completed!");
+ } else {
+ try {
+ final LocalDate dueBy = wrapperFactory.wrap(this).getDueBy(); // <3>
+ if (dueBy != null) {
+ buf.append(" due by", dueBy);
+ }
+ } catch(final HiddenException ignored) { // <4>
+ }
+ }
+ return buf.toString();
+}
+----
+<1> simple xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[tility class] to help construct the title string
+<2> imperative conditional logic
+<3> using the xref:rgsvc.adoc#_rgsvc-api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
+<4> ... but ignore if not
+
+As the example above shows, the implementation can be as complex as you like.
+
+In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
+
+
+See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+
+
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
new file mode 100644
index 0000000..3fae49e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
@@ -0,0 +1,27 @@
+[[_rgcms_methods_reserved_validate]]
+= `validate()`
+: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 `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
+
+
+[WARNING]
+====
+(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
+====
+
+
+The signature of the method is:
+
+[source,java]
+----
+public String validate() { ... }
+----
+
+where the returned string is the reason that the invocation is vetoed.
+
+Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
index 660f74e..b494369 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api.adoc
@@ -132,7 +132,7 @@ xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`] for persistent `Comm
`services.` +
`fixturespec` +
`FixtureScriptsDefault`]
-|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
+|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
|`FixtureScriptsDefault` +
``o.a.i.core`` +
``isis-core-applib``
@@ -214,7 +214,7 @@ SpecificationProvider`].
|xref:rgsvc.adoc#_rgsvc-api_SudoService[`o.a.i.applib.` +
`services.sudo` +
`SudoService`]
-|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_manpage-FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
+|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
|`SudoServiceDefault` +
``o.a.i.core`` +
``isis-core-runtime``
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
index d24f7fb..0e5a50f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_object-creation-api.adoc
@@ -21,7 +21,7 @@ public interface DomainObjectContainer {
}
----
<1> create a new non-persisted domain entity. Any services will be automatically injected into the service
-<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_manpage-AbstractViewModel[ViewModel#viewModelMemento()]. In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
+<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[ViewModel#viewModelMemento()]. In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
<3> programmatically instantiate a mixin, as annotated with
xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
@@ -40,9 +40,9 @@ Doing this will not inject any domain services, but they can be injected manuall
[NOTE]
====
-Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_manpage-created[`created()`]
+Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_created[`created()`]
callback, and in addition any default values for properties (either explicitly set by
-xref:rgcms.adoc#_rgcms_methods_prefixes_manpage-default[`default...()`] or defaulted implicitly according to Apache Isis'
+xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] or defaulted implicitly according to Apache Isis'
own conventions) will not be called either. If you don't intend to use these features, though, the net effect is code
that has less coupling to Isis and is arguably easier to understand (has "less magic" happening).
====
http://git-wip-us.apache.org/repos/asf/isis/blob/43fc7bc1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
index a3de5d0..8c6378f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_DomainObjectContainer_presentation-api.adoc
@@ -7,7 +7,7 @@
-A responsibility of every domain object is to return a title. This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_manpage-title[`title()`] method.
+A responsibility of every domain object is to return a title. This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method.
It's quite common for titles to be built up of the titles of other objects. If using building up the title using `@Title` then Apache Isis will automatically use the title of the objects referenced by the annotated properties. We also need programmatic access to these titles if going the imperative route.