You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/05/20 06:37:31 UTC
[08/10] isis git commit: ISIS-1133: reference chapter (annotations,
mostly)
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-domainservicelayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-domainservicelayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-domainservicelayout.adoc
new file mode 100644
index 0000000..e41389f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-domainservicelayout.adoc
@@ -0,0 +1,159 @@
+= anchor:reference-annotations_manpage-[]`@DomainServiceLayout`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @DomainServiceLayout (1.8.0)
+
+The `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics
+within a single annotation.
+
+*
+
+`named` - name of this class (overriding the name derived from its name in code)
+
+*
+
+`menuBar` - the menubar in which the menu that holds this service's actions should reside.
+
+*
+
+`menuOrder` - the order of the service's menu with respect to other service's (equivalent to deprecated `@DomainService#menuBar()`).
+
+The `menuBar` can be set to PRIMARY, SECONDARY or TERTIARY. In the Wicket viewer the PRIMARY menu bar is left-aligned,
+the SECONDARY menu bar is right aligned, and the TERTIARY menu bar is associated with the user's name (far top-right).
+
+== See also
+
+Other domain semantics:
+
+* link:./Property.html[@Property]
+* link:./Collection.html[@Collection]
+* link:./Action.html[@Action]
+* link:./Parameter.html[@Parameter]
+* link:./DomainObject.html[@DomainObject]
+* link:./DomainService.html[@DomainService]
+* link:./ViewModel.html[@ViewModel]
+
+Corresponding view layer ("Layout") annotation:
+
+* link:./DomainServiceLayout.html[@DomainServiceLayout]
+
+
+
+
+
+
+
+
+
+
+
+
+== `named()`
+
+Title: @Named
+
+____
+
+Deprecated, use instead link:./DomainObjectLayout.html[@DomainObjectLayout#named()], link:./PropertyLayout.html[@PropertyLayout#named()], link:./CollectionLayout.html[@CollectionLayout#named()], link:./ActionLayout.html[@ActionLayout#named()] and link:./ParameterLayout.html[@ParameterLayout#named()], or use link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `@Named` annotation is used when you want to specify the way
+something is named on the user interface i.e. when you do not want to
+use the name generated automatically by the system. It can be applied to
+objects, members (properties, collections, and actions) and to
+parameters within an action method.
+
+____
+
+*Warning*
+
+Generally speaking it is better to rename the property, collection or
+action. The only common case where `@Named` is common is to rename
+parameters for built-in value types. Even here though a custom value
+type can be defined using `@Value` so that the value type is used as the
+parameter name. `@Named` may also be used if the name needs punctuation
+or other symbols in the name presented to the user.
+
+____
+
+=== Specifying the name of an object
+
+By default the name of an object is derived, reflectively from the class
+name. To specify a different name for an object, use the `@Named`
+annotation in front of the class declaration.
+
+For example:
+
+[source]
+----
+@Named("Customer")
+public class CustomerImpl implements Customer{
+ ...
+}
+----
+
+See also the `@Plural` annotation <!--, ?-->.
+
+=== Specifying the name of a class member
+
+By default, the name of a class member (a property, collection or
+action) presented to the user is derived, reflectively, from the name of
+the member defined in the program code. To specify a different name use
+the `@Named
+`annotation immediately before the member declaration.
+
+For example:
+
+[source]
+----
+public class Customer {
+
+ public String getFirstName() { ... }
+
+ public String getSurname() { ... }
+
+ public CreditRating getCreditRating() { ... }
+}
+----
+
+Note that the framework provides a separate and more powerful mechanism
+for internationalisation.
+
+=== Specifying the name for an action parameter
+
+The most common usage of `@Named` is be to specify names for the
+parameters of an action. This is because the parameter name declared in
+the code for the action method cannot be picked up reflectively (by
+default, the user interface will use the type of the parameter as the
+name; for a `String` or a `Boolean`, this is almost certainly not what is
+required).
+
+To specify the name of a parameter, the `@Named` annotation is applied
+'in-line' (i.e. preceding the individual parameter declaration.
+
+For example:
+
+[source]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product
+ ,@Named("Quantity")
+ int quantity) {
+ Order order = newTransientInstance(Order.class);
+ order.modifyCustomer(this);
+ order.modifyProduct(product);
+ order.setQuantity(quantity);
+ return order;
+ }
+ ...
+}
+----
+
+An alternative is to use a value type (though this introduces additional mapping complexity for both viewers and objectstore) <!--, as described in ?-->.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-facets.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-facets.adoc
new file mode 100644
index 0000000..0fef90c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-facets.adoc
@@ -0,0 +1,15 @@
+= anchor:reference-annotations_manpage-[]`@Facets`
+: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/
+
+IMPORTANT: TODO
+
+
+
+Title: @Facets
+
+The `@Facets` annotation specifies `FacetFactory` implementations and so can
+be used to run install arbitrary `Facet`s for a type. Generally this is
+not needed, but can be useful for overriding a custom programming model
+where a `FacetFactory` is not typically included.
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-homepage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-homepage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-homepage.adoc
new file mode 100644
index 0000000..adcfa88
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-homepage.adoc
@@ -0,0 +1,21 @@
+= anchor:reference-annotations_manpage-[]`@HomePage`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @HomePage
+
+____
+
+Support
+
+Currently only by the Wicket viewer
+
+____
+
+The `@HomePage` annotation should be applied to a single (no-arg) action on a domain service, and the results used as the contents for the home page.
+
+Typically this action would return a link:../../more-advanced-topics/ViewModel.html[View Model] representing a dashboard from which the user can navigate to commonly used objects and invoked actions. But it could also simply invoke an action that returns an entity (eg representing the currently logged-on user) or a list of objects.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-inject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-inject.adoc
new file mode 100644
index 0000000..74b2896
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-inject.adoc
@@ -0,0 +1,15 @@
+= anchor:reference-annotations_manpage-[]`@Inject` (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/
+
+IMPORTANT: TODO
+
+
+Title: @javax.inject.Inject
+
+____
+
+this is a stub
+
+____
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-membergrouplayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-membergrouplayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-membergrouplayout.adoc
new file mode 100644
index 0000000..f54957d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-membergrouplayout.adoc
@@ -0,0 +1,8 @@
+= anchor:reference-annotations_manpage-[]`@MemberGroupLayout`
+: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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-memberorder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-memberorder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-memberorder.adoc
new file mode 100644
index 0000000..45e3ef5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-memberorder.adoc
@@ -0,0 +1,127 @@
+= anchor:reference-annotations_manpage-[]`@MemberGroupLayout`
+: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/
+
+IMPORTANT: TODO
+
+
+
+
+Title: @MemberOrder
+
+____
+
+See also link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+`@MemberOrder` is the recommended mechanism for specifying the order in
+which fields and/or actions are presented to the user. (`@ActionOrder`
+and `@FieldOrder` provide alternative, deprecated mechanisms).
+
+`@MemberOrder` is specified at the individual member level, relative to
+other members, as a string. The simplest convention is to use numbers -
+1, 2, 3 - though it is a better idea to leave gaps in the numbers - 10,
+20, 30 perhaps - such that a new member may be added without having to
+edit existing numbers. A useful alternative is to adopt the
+'dewey-decimal' notation - 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -
+which allows for an indefinite amount of future insertion, and allows
+subclasses to insert their class members as required.
+
+For example:
+
+[source]
+----
+public Class Customer {
+ @MemberOrder(sequence="2.1")
+ public String getAddress() {...}
+ public void setAddress(value as String) {...}
+
+ @MemberOrder(sequence="1.1")
+ public String getFirstName() {...}
+ public void setFirstName(value as String) {...}
+
+ @MemberOrder(sequence="1.2")
+ public String getLastName() {...}
+ public void setLastName(value as String) {...}
+
+ @MemberOrder(sequence="3")
+ public Date getDateOfBirth() {...}
+ public void setDateOfBirth(value as Date) {...}
+ ...
+}
+----
+
+If a member does not have a specified order then it will be placed after
+those that are specified. Two members may have the same sequence
+specifier, but in such a case the relative ordering of those members
+will be indeterminate.
+
+____
+
+*Note*
+
+Certain styles of user interface may lay out an object's properties
+and its collections separately, in which case the relative member
+order of properties and collections will be evaluated separately. In
+general, though, consider the layout of all properties and collections
+together, and of all actions together.
+
+____
+
+As a refinement to this, some viewers support the notion of grouping
+members together. In this case the `name` attribute can be specified.
+
+For example, the following can be used to group properties:
+
+[source]
+----
+public Class Customer {
+ @MemberOrder(name="General", sequence="1.1")
+ public String getFirstName() {...}
+ public void setFirstName(value as String) {...}
+
+ @MemberOrder(name="General", sequence="1.2")
+ public String getLastName() {...}
+ public void setLastName(value as String) {...}
+
+ @MemberOrder(name="Other", sequence="1")
+ public String getAddress() {...}
+ public void setAddress(value as String) {...}
+
+ @MemberOrder(name="Dates", sequence="1")
+ public Date getDateOfBirth() {...}
+ public void setDateOfBirth(value as Date) {...}
+ ...
+}
+----
+
+In this case the `sequence` is ordered with respect to the `name`. If
+using group names in this way, typically the `@MemberGroups` annotation
+<!--(see ?)--> should also be specified, allowing the order of the groups
+themselves to be sorted.
+
+Grouping can also be performed on actions. Some viewers (for example the
+Wicket viewer) support the idea that the group name can be the name of a
+collection. In this case, the action is rendered "near to" the
+collection (for example, to support add or remove of elements).
+
+For example:
+
+[source]
+----
+public Class Customer {
+
+ public List<CommunicationChannel> getCommunicationChannels() { ... }
+
+ ...
+ @MemberOrder(name="communicationChannels", sequence="1.1")
+ public void addCommunicationChannel(...) { ... }
+
+ @MemberOrder(name="communicationChannels", sequence="1.2")
+ public void removeCommunicationChannel(...) { ... }
+
+ ...
+}
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-minlength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-minlength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-minlength.adoc
new file mode 100644
index 0000000..a5442dd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-minlength.adoc
@@ -0,0 +1,36 @@
+= anchor:reference-annotations_manpage-[]`@MinLength`
+: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/
+
+IMPORTANT: TODO
+
+
+
+
+Title: @MinLength
+
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an link:../../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html[auto-complete].
+
+For example:
+
+[source]
+----
+public ToDoItem add(
+ @TypicalLength(20)
+ final ToDoItem toDoItem) {
+ getDependencies().add(toDoItem);
+ return this;
+}
+public List<ToDoItem> autoComplete0Add(
+ final @MinLength(2)
+ String search) {
+ final List<ToDoItem> list = toDoItems.autoComplete(search);
+ list.removeAll(getDependencies());
+ list.remove(this);
+ return list;
+}
+----
+
+
+The `@Parameter(minLength=...)`e can also be used (even though strictly speaking the search argument is not a parameter of the action).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameter.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameter.adoc
new file mode 100644
index 0000000..8d6c437
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameter.adoc
@@ -0,0 +1,318 @@
+= anchor:reference-annotations_manpage-[]`@Parameter`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @Parameter (1.8.0)
+
+____
+
+stub
+
+____
+
+The `@Parameter` annotation applies to action parameters collecting together all domain semantics within a single annotation.
+
+== Source code
+
+See <a href="https://issues.apache.org/jira/browse/ISIS-970">ISIS-970</a> and <a href="https://github.com/apache/isis/blob/master/core/applib/src/main/java/org/apache/isis/applib/annotation/Parameter.java">@Parameter</a> source code.
+
+== See also
+
+Other domain semantics:
+
+* link:./Property.html[@Property]
+* link:./Collection.html[@Collection]
+* link:./Action.html[@Action]
+* link:./DomainObject.html[@DomainObject]
+* link:./DomainService.html[@DomainService]
+* link:./ViewModel.html[@ViewModel]
+
+Corresponding view layer ("Layout") annotation:
+
+* link:./ParameterLayout.html[@ParameterLayout]
+
+
+
+
+
+== `maxLength()`
+
+Title: @MaxLength
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#maxLength()] and link:./Parameter.html[@Parameter#maxLength()] .
+
+____
+
+The `@MaxLength` annotation indicates the maximum number of characters
+that the user may enter into a `String` property, or a `String`
+parameter in an action, or for a string-based value type. It is ignored
+if applied to any other type.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @MaxLength(30)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ ...
+}
+----
+
+Or, on an action parameter:
+
+[source]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @MaxLength(30)
+ @Named("First Name") String firstName
+ ,@MaxLength(30)
+ @Named("Last Name") String lastName) {
+ ...
+}
+----
+
+Or, for a value type:
+
+[source]
+----
+@Value(...)
+@MaxLength(30)
+public class CustomerFirstName {
+ ...
+}
+----
+
+If the model is being persisted to a relational database then
+`@MaxLength` should be specified for all `String` properties and action
+parameters.
+
+
+
+
+
+
+Title: @MinLength
+
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an link:../../how-tos/how-to-03-025-How-to-specify-an-autocomplete-for-an-action-parameter.html[auto-complete].
+
+For example:
+
+[source]
+----
+public ToDoItem add(
+ @TypicalLength(20)
+ final ToDoItem toDoItem) {
+ getDependencies().add(toDoItem);
+ return this;
+}
+public List<ToDoItem> autoComplete0Add(
+ final @MinLength(2)
+ String search) {
+ final List<ToDoItem> list = toDoItems.autoComplete(search);
+ list.removeAll(getDependencies());
+ list.remove(this);
+ return list;
+}
+----
+
+
+
+
+
+
+== `mustSatisfy()`
+
+Title: @MustSatisfy
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#mustSatisfy()] and link:./Parameter.html[@Parameter#mustSatisfy()].
+
+____
+
+The `@MustSatisfy` annotation allows validation to be applied to
+properties and parameters using an (implementation of a)
+`org.apache.isis.applib.spec.Specification` object.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @MustSatisfy(StartWithCapitalLetterSpecification.class)
+ public String getFirstName() { ... }
+ ...
+}
+----
+
+Or, on an action parameter:
+
+[source]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @MustSatisfy(StartWithCapitalLetterSpecification.class)
+ @Named("First Name") firstName
+ ,@MustSatisfy(StartWithCapitalLetterSpecification.class)
+ @Named("Last Name") lastName) {
+ ...
+ }
+ ...
+}
+----
+
+The `Specification` is consulted during validation, being passed the
+proposed value.
+
+An alternative to using `@MustSatisfy` is to define a custom value type (though this introduces additional mapping complexity for both viewers and objectstore).
+
+
+
+
+
+
+== `optionality()`
+
+Title: @Optional
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#optionality()] and link:./Parameter.html[@Parameter#optionality()].
+
+____
+
+By default, the system assumes that all properties of an object are
+required, and therefore will not let the user save a new object unless a
+value has been specified for each property. Similarly, by default, the
+system assumes that all parameters in an action are required and will
+not let the user execute that action unless values have been specified
+for each parameter.
+
+To indicate that either a property, or an action parameter, is optional,
+use the `@Optional` annotation.
+
+____
+
+*Note*
+
+The `@Optional`annotation has no meaning for a primitive property (or
+parameter) such as `int` - because primitives will always return a
+default value (e.g. zero). If optionality is required, then use the
+corresponding wrapper class (e.g. `java.lang.Integer`).
+
+____
+
+=== Making a property optional
+
+Annotate the getter to indicate that a property is `@Optional`. For
+example:
+
+[source]
+----
+public class Order {
+ public Product getProduct() { ... }
+
+ public java.util.Date getShipDate() { ... }
+ public void setShipDate(Date java.util.shipDate) { ... }
+
+ @Optional
+ public String getComments() { ... }
+ public void setComments(String comments) { ... }
+}
+----
+
+Here the `product` and `shipDate` properties are both required, but the
+`comments` property is optional.
+
+=== Making an action parameter optional
+
+To indicate that an action may be invoked without having to specify a
+value for a particular parameter, annotate with `@Optional`. For
+example:
+
+[source]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product
+ ,@Named("Quantity") int quantity
+ ,@Optional @Named("Special Instructions") String instr) {
+ ...
+ }
+ ...
+}
+----
+
+
+
+
+== `regexPattern()`
+
+Title: @RegEx
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#regex()] and link:./Parameter.html[@Parameter#regex()].
+
+____
+
+The `@RegEx` annotation may be applied to any string property, or to any
+parameter within an action method. It can also be applied to any
+string-based value type. It serves both to validate and potentially to
+normalise the format of the input. `@Regex` is therefore similar in use
+to `@Mask` <!--(see ?)--> but provides more flexibility.
+
+The syntax is:
+
+`@RegEx(validation = "regEx string",
+ format = "regEx string", caseSensitive =
+ <true|false>)`
+
+Only the first parameter is required; the `format` defaults to "no
+formatting", and `caseSensitive` defaults to false.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ public String getEmail() {}
+ ...
+}
+----
+
+Or, on a parameter:
+
+[source]
+----
+public class Customer {
+ public void updateEmail(
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ @Named("Email") String email) {
+ ...
+ }
+ ...
+)
+----
+
+Or, on a value type:
+
+[source]
+----
+@Value(...)
+@RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+public class EmailAddress {
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameterlayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameterlayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameterlayout.adoc
new file mode 100644
index 0000000..206ca3b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-parameterlayout.adoc
@@ -0,0 +1,553 @@
+= anchor:reference-annotations_manpage-[]`@ParameterLayout`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @ParameterLayout (1.8.0)
+
+The `@ParameterLayout` annotation applies to action parameters, collecting together all UI hints within a single
+annotation.
+
+* `cssClass` - the css class that a parameter should have, to allow more targetted styling in `application.css`
+* `describedAs` - description of this parameter, eg to be rendered in a tooltip.
+* `labelPosition` - in forms, the positioning of the label (LEFT, TOP or NONE) relative to the parameter value. For boolean parameters it is also possible to specify RIGHT. Defaults to LEFT unless `multiLine` also specified (see below)
+* `named` -the name of this parameter. For Java 7 this is generally required. For Java 8, the name can be inferred from the code so this attribute allows the name to be overridden.
+* `namedEscaped` - whether to HTML escape the name of this parameter. Defaults to true.
+* `multiLine` - for string parameters, render as a text area over multiple lines. If set >1, then `labelPosition` defaults to TOP unless otherwise specified.
+* `renderedAsDayBefore` - for date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
+* `typicalLength` -the typical entry length of a field, use to determine the optimum width for display
+
+For example:
+
+[source]
+----
+public class ToDoItem {
+
+ public ToDoItem updateDescription(
+ @ParameterLayout(
+ cssClass="x-key",
+ describedAs="What needs to be done",
+ labelPosition=LabelPosition.LEFT,
+ named="Description of this <i>item</i>",
+ namedEscaped=false,
+ typicalLength=80)
+ final String description) {
+ setDescription(description);
+ return this;
+ }
+
+ public ToDoItem updateNotes(
+ @ParameterLayout(
+ describedAs="Additional notes",
+ labelPosition=LabelPosition.TOP,
+ named="Notes",
+ multiLine=8)
+ final String notes) {
+ setNotes(notes);
+ return this;
+ }
+
+ ...
+}
+----
+
+== Alternatives (`.layout.json`)
+
+Unlike link:./PropertyLayout.html[properties], it (currently) isn't possible to specify layout hints for action parameters using the `.layout.json` file.
+
+== Specifying a default setting
+
+If you want a consistent look-n-feel throughout the app, eg all action parameter labels to the top, then it'd be rather frustrating to have to annotate every property.
+
+Instead, a default can be specified in `isis.properties`:
+
+[source]
+----
+isis.viewers.parameterLayout.labelPosition=TOP
+----
+
+or
+
+[source]
+----
+isis.viewers.parameterLayout.labelPosition=LEFT
+----
+
+If these are not present then Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
+
+== See also
+
+Similar layout annotations exist for other elements of the metamodel:
+
+* link:./PropertyLayout.html[@PropertyLayout] for properties
+* link:./CollectionLayout.html[@CollectionLayout] for collections
+* link:./ActionLayout.html[@ActionLayout] for actions
+* link:./DomainObjectLayout.html[@DomainObjectLayout]
+* link:./DomainServiceLayout.html[@DomainServiceLayout]
+* link:./ViewModelLayout.html[@ViewModelLayout]
+
+Corresponding domain semantics:
+
+* link:./Parameter.html[@Parameter]
+
+
+
+
+== `cssClass()`
+
+Title: @CssClass
+
+____
+
+Deprecated, use instead link:./DomainObjectLayout.html[@DomainObjectLayout#cssClass()], link:./PropertyLayout.html[@PropertyLayout#cssClass()], link:./CollectionLayout.html[@CollectionLayout#cssClass()], link:./ActionLayout.html[@ActionLayout#cssClass()] and link:./ParameterLayout.html[@ParameterLayout#cssClass()], or use link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `CssClass` annotation applies to object and also to any object member
+(property, collection or action). It is used by the Wicket viewer as a UI hint
+to render specified CSS classes around the representation of the element.
+
+Application-specific CSS can then be used to target and adjust the UI representation
+of that particular element.
+
+For example:
+
+[source]
+----
+@CssClass("x-main")
+public class ToDoItem { ... }
+----
+
+or
+
+[source]
+----
+public class ToDoItem {
+
+ @CssClass("x-key")
+ public LocalDate getDueBy() { ... }
+
+}
+----
+
+== Alternatives (`.layout.json`)
+
+As an alternative to using the `@CssClass` annotation, the `.layout.json`
+link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layout file]
+can be specified, eg:
+
+[source]
+----
+{
+ "span": 6,
+ "memberGroups": {
+ "Priority": {
+ "members": {
+ ...
+ "dueBy": {
+ "cssClass": { "value": "x-key" }
+ }
+ ....
+ }
+ },
+ ...
+ }
+}
+----
+
+Note that this (currently) only supports class members, not classes
+
+== See also (1.8.0)
+
+The similar link:./CssClassFa-deprecated.html[CssClassFa] annotation 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 on action butotns or as the icon for classes.
+
+
+
+
+== `describedAs()`
+
+Title: @DescribedAs
+
+____
+
+Deprecated, use instead link:./DomainObjectLayout.html[@DomainObjectLayout#describedAs()], link:./PropertyLayout.html[@PropertyLayout#describedAs()], link:./CollectionLayout.html[@CollectionLayout#describedAs()], link:./ActionLayout.html[@ActionLayout#describedAs()] and link:./ParameterLayout.html[@ParameterLayout#describedAs()], or use link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `@DescribedAs` annotation is used to provide a short description of
+something that features on the user interface. How this description is
+used will depend upon the viewing mechanism - but it may be thought of
+as being like a 'tool tip'.
+
+Descriptions may be provided for objects, members (properties,
+collections and actions), and for individual parameters within an action
+method. `@DescribedAs` therefore works in a very similar manner to
+`@Named` <!--(see ?)-->.
+
+=== Providing a description for an object
+
+To provide a description for an object, use the `@DescribedAs`
+annotation immediately before the declaration of that object class.
+
+For example:
+
+[source]
+----
+@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 {
+ ...
+}
+----
+
+=== Providing a description for an object member
+
+Any member (property, collection or action) may provide a description.
+To specify this description, use the `@DescribedAs` annotation
+immediately before the declaration of that member.
+
+For example:
+
+[source]
+----
+public class Customer {
+ @DescribedAs("The name that the customer has indicated that they wish to be " +
+ "addressed as (e.g. Johnny rather than Jonathan)")
+ public String getFirstName() { ... }
+}
+----
+
+=== Providing a description for an action parameter
+
+To provide a description for an individual action parameter, use the
+`@DescribedAs` annotation in-line i.e. immediately before the parameter
+declaration.
+
+For example:
+
+[source]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product,
+ @Named("Quantity")
+ @DescribedAs("The quantity of the product being ordered")
+ int quantity) {
+ Order order = createTransientInstance(Order.class);
+ order.modifyCustomer(this);
+ order.modifyProduct(product);
+ order.setQuantity(quantity);
+ return order;
+ }
+ ...
+}
+----
+
+
+
+
+
+== `multiLine()`
+
+Title: @MultiLine
+
+____
+
+Deprecated, use instead link:./PropertyLayout.html[@PropertyLayout#multiLine()] and link:./ParameterLayout.html[@ParameterLayout#multiLine()] or link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `@MultiLine` annotation provides information about the carriage
+returns in a `String` property or action parameter, or for a
+string-based value type. It also implies a hint to the viewer that the
+widget to be used should be over multiple lines (eg a text area rather
+than a text field), with appropriate wrapping and/or scrollbars.
+
+More formally, the annotation indicates that:
+
+*
+
+the `String` property or parameter may contain carriage returns, and
+
+*
+
+(optionally) the typical number of such carriage returns (meaning
+the number of rows in the text area), and
+
+*
+
+(optionally) that the text should be wrapped (the default is that
+text is not wrapped).
+
+The syntax is:
+
+`@MultiLine([numberOfLines=<typicalNumberOfCRs>]
+ [,preventWrapping=<false|true>])`
+
+For example:
+
+[source]
+----
+public class BugReport {
+ @MultiLine(numberOfLines=10)
+ public String getStepsToReproduce() { ... }
+ public void setStepsToReproduce(String stepsToReproduce) { ... }
+ ...
+}
+----
+
+Here the `stepsToReproduce` may be displayed in a text area of 10 rows,
+with no wrapping. A horizontal scrollbar may appear if the number of
+characters on any given row exceeds the width.
+
+Another example:
+
+[source]
+----
+public class Email {
+ @MultiLine(numberOfLines=20, preventWrapping=false)
+ public String getBody() { ... }
+ public void setBody(String body) { ... }
+ ...
+}
+----
+
+Here the body should be displayed in a text area of 20 rows, with
+wrapping.
+
+If the annotation is combined with the `@TypicalLength`, then the
+expected width of the text area in the user interface will be determined
+by the value of the typical length divided by the number of specified
+lines. For example:
+
+[source]
+----
+public class Email {
+ @MultiLine(numberOfLines=20, preventWrapping=false)
+ @TypicalLength(800)
+ public String getBody() { ... }
+ public void setBody(String body) { ... }
+ ...
+}
+----
+
+Here the body will (likely be) displayed in a text area of 20 rows, with
+40 columns.
+
+
+
+
+
+
+
+
+
+
+
+
+
+== `named()`
+
+Title: @Named
+
+____
+
+Deprecated, use instead link:./DomainObjectLayout.html[@DomainObjectLayout#named()], link:./PropertyLayout.html[@PropertyLayout#named()], link:./CollectionLayout.html[@CollectionLayout#named()], link:./ActionLayout.html[@ActionLayout#named()] and link:./ParameterLayout.html[@ParameterLayout#named()], or use link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `@Named` annotation is used when you want to specify the way
+something is named on the user interface i.e. when you do not want to
+use the name generated automatically by the system. It can be applied to
+objects, members (properties, collections, and actions) and to
+parameters within an action method.
+
+____
+
+*Warning*
+
+Generally speaking it is better to rename the property, collection or
+action. The only common case where `@Named` is common is to rename
+parameters for built-in value types. Even here though a custom value
+type can be defined using `@Value` so that the value type is used as the
+parameter name. `@Named` may also be used if the name needs punctuation
+or other symbols in the name presented to the user.
+
+____
+
+=== Specifying the name of an object
+
+By default the name of an object is derived, reflectively from the class
+name. To specify a different name for an object, use the `@Named`
+annotation in front of the class declaration.
+
+For example:
+
+[source]
+----
+@Named("Customer")
+public class CustomerImpl implements Customer{
+ ...
+}
+----
+
+See also the `@Plural` annotation <!--, ?-->.
+
+=== Specifying the name of a class member
+
+By default, the name of a class member (a property, collection or
+action) presented to the user is derived, reflectively, from the name of
+the member defined in the program code. To specify a different name use
+the `@Named
+`annotation immediately before the member declaration.
+
+For example:
+
+[source]
+----
+public class Customer {
+
+ public String getFirstName() { ... }
+
+ public String getSurname() { ... }
+
+ public CreditRating getCreditRating() { ... }
+}
+----
+
+Note that the framework provides a separate and more powerful mechanism
+for internationalisation.
+
+=== Specifying the name for an action parameter
+
+The most common usage of `@Named` is be to specify names for the
+parameters of an action. This is because the parameter name declared in
+the code for the action method cannot be picked up reflectively (by
+default, the user interface will use the type of the parameter as the
+name; for a `String` or a `Boolean`, this is almost certainly not what is
+required).
+
+To specify the name of a parameter, the `@Named` annotation is applied
+'in-line' (i.e. preceding the individual parameter declaration.
+
+For example:
+
+[source]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product
+ ,@Named("Quantity")
+ int quantity) {
+ Order order = newTransientInstance(Order.class);
+ order.modifyCustomer(this);
+ order.modifyProduct(product);
+ order.setQuantity(quantity);
+ return order;
+ }
+ ...
+}
+----
+
+An alternative is to use a value type (though this introduces additional mapping complexity for both viewers and objectstore) <!--, as described in ?-->.
+
+
+
+
+
+== `renderedAsDayBefore()`
+
+Title: @RenderedAsDayBefore
+
+____
+
+Deprecated, use instead link:./PropertyLayout.html[@PropertyLayout#renderedAsDayBefore()] and link:./ParameterLayout.html[@ParameterLayout#renderedAsDayBefore()] or link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+A rendering hint, instructing the viewer that the date should as one day prior to the actually stored date.
+
+This is intended to be used so that an exclusive end date of an interval can be rendered as 1 day before the actual value stored.
+
+For example:
+
+[source]
+----
+public LocalDate getStartDate() { ... }
+
+@RenderedAsDayBefore
+public LocalDate getEndDate() { ... }
+----
+
+Here, the interval of the [1-may-2013,1-jun-2013) would be rendered as the dates 1-may-2013 for the start date but using 31-may-2013 (the day before) for the end date.
+
+What is stored in the domain object, itself, however, the value stored is 1-jun-2013.
+
+
+
+
+
+
+== `typicalLength()`
+
+Title: @TypicalLength
+
+____
+
+Deprecated, use instead link:./PropertyLayout.html[@PropertyLayout#typicalLength()] and link:./ParameterLayout.html[@ParameterLayout#typicalLength()] or link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
+
+____
+
+The `@TypicalLength` annotation indicates the typical length of a
+`String` property or `String` parameter in an action. It can also be
+specified for string-based value types.
+
+The information is generally used by the viewing mechanism to determine
+the space that should be given to that property or parameter in the
+appropriate view. If the typical length is the same as the `@MaxLength`
+<!--(see ?)--> then there is no need to specify `@TypicalLength` as well. If
+the value specified is zero or negative then it will be ignored.
+
+For example, for a property:
+
+[source]
+----
+public class Customer {
+ @MaxLength(30)
+ @TypicalLength(20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+}
+----
+
+Or, for a parameter:
+
+[source]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @TypicalLength(20)
+ @Named("First Name") String firstName
+ ,@TypicalLength(20)
+ @Named("Last Name") String lastName) {
+ ...
+ }
+ ...
+}
+----
+
+Or, for value type:
+
+[source]
+----
+@Value(...)
+@TypicalLength(20)
+public class FirstName {
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-programmatic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-programmatic.adoc
new file mode 100644
index 0000000..c993d28
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-programmatic.adoc
@@ -0,0 +1,45 @@
+= anchor:reference-annotations_manpage-[]`@Programmatic`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @Programmatic
+
+The `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel. This means it won't appear in any UI, and it won't appear in any mementos/snapshots.
+
+A common use-case is to ignore implementation-level artifacts. For
+example:
+
+[source]
+----
+public class Customer implements Comparable<Customer> {
+ ...
+ @Programmatic
+ public int compareTo(Customer c) {
+ return getSalary() - c.getSalary();
+ }
+ ...
+}
+----
+
+Note that `@Programmatic` does not simply imply `@Hidden` and `@NotPersisted`;
+it actually means that the class member will not be part of the Isis
+metamodel.
+
+
+
+Title: @Ignore (deprecated)
+
+____
+
+Deprecated, use instead link:./Action.html[@Action#semantics()].
+
+____
+
+Equivalent to using `@Programmatic`.
+
+The `@Programmatic` annotation was
+introduced because `@Ignore` can easily clash with `@org.junit.Ignore`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/74e29802/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-property.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-property.adoc
new file mode 100644
index 0000000..232f4ed
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-property.adoc
@@ -0,0 +1,767 @@
+= anchor:reference-annotations_manpage-[]`@Property`
+: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/
+
+IMPORTANT: TODO
+
+
+Title: @Property (1.8.0)
+
+____
+
+stub
+
+____
+
+The `@Property` annotation applies to properties collecting together all domain semantics within a single annotation.
+
+It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
+
+== Source code
+
+See <a href="https://issues.apache.org/jira/browse/ISIS-970">ISIS-970</a> and <a href="https://github.com/apache/isis/blob/master/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java">@Property</a> source code.
+
+== See also
+
+Other domain semantics:
+
+* link:./Collection.html[@Collection]
+* link:./Action.html[@Action]
+* link:./Parameter.html[@Parameter]
+* link:./DomainObject.html[@DomainObject]
+* link:./DomainService.html[@DomainService]
+* link:./ViewModel.html[@ViewModel]
+
+Corresponding view layer ("Layout") annotation:
+
+* link:./PropertyLayout.html[@PropertyLayout]
+
+
+
+
+
+
+
+== `editing()`
+
+Title: @Disabled
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#editing()], link:./Collection.html[@Collection#editing()], and also link:./DomainObject.html[@DomainObject#editing()]
+
+*Support*
+
+* Fully supported by: Wicket viewer; other viewers do not yet support the `where` attribute.
+
+____
+
+The `@Disabled` annotation means that the member cannot be used in any
+instance of the class. When applied to the property it means that the
+user may not modify the value of that property (though it may still be
+modified programmatically). When applied to an action method, it means
+that the user cannot invoke that method.
+
+For example:
+
+[source]
+----
+public class Customer {
+ @Disabled
+ public void assessCreditWorthiness() { ... }
+
+ @Disabled
+ public int getInitialCreditRating(){ ... }
+ public void setInitialCreditRating(int initialCreditRating) { ... }
+}
+----
+
+Note that if an action is marked as `@Disabled`, it will be shown on the
+user interface but cannot ever be invoked. The only possible reason we
+can think to do this is during prototyping, to indicate an action that
+is still to be developed. If a method is intended for programmatic use,
+but not intended ever to be invoked directly by a user, then it should
+be marked as `@Hidden` instead.
+
+This annotation can also take two parameter indicating where (in the UI)
+it is to be disabled, and when (in the object's lifecycle) it is to be
+disabled. For example:
+
+[source]
+----
+public class Customer {
+ (when=When.UNTIL_PERSISTED)
+ public void assessCreditWorthiness() { ... }
+}
+----
+
+would disable the action until the object has been saved. And:
+
+[source]
+----
+public class Customer {
+ (where=Where.PARENTED_TABLES)
+ public void getFirstName() { ... }
+}
+----
+
+would disable the property in parented tables but not in regular object
+forms (though note: this would only be used by viewers that provide
+in-table editing capability).
+
+The acceptable values for the `where` parameter are:
+
+* `Where.ANYWHERE` +
++
+The member should be disabled everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The member should be disabled when displayed within an object form.
+For most viewers, this applies to property and collection members,
+not actions.
+
+* `Where.PARENTED_TABLES` +
++
+The member should be disabled when displayed as a column of a table
+within a parent object's collection. For most (all?) viewers, this
+will have meaning only if applied to a property member.
+
+* `Where.STANDALONE_TABLES` +
++
+The member should be disabled when displayed as a column of a table
+showing a standalone list of objects, for example as returned by a
+repository query. For most (all?) viewers, this will have meaning
+only if applied to a property member.
+
+* `Where.ALL_TABLES` +
++
+The member should be disabled when displayed as a column of a table,
+either an object's * collection or a standalone list. This combines
+`PARENTED_TABLES` and `STANDALONE_TABLES`
+
+* `Where.NOWHERE` +
++
+Has no meaning for the `@Disabled` annotation (though is used by the
+`@Hidden` annotation which also uses the `Where` enum<!--, see ?-->).
+
+The acceptable values for the `when` parameter are:
+
+* `When.ALWAYS` +
++
+The member should be disabled at all times.
+
+* `When.NEVER` +
++
+The member should never be disabled (unless disabled through some
+other mechanism, for example an imperative disableXxx() supporting
+method)..
+
+* `When.ONCE_PERSISTED` +
++
+The member should be enabled for transient objects, but disabled for
+persisted objects.
+
+* `When.UNTIL_PERSISTED` +
++
+The member should be disabled for transient objects, but enabled for
+persisted objects.
+
+By default the annotated property or action is always disabled (ie
+defaults to `Where.ANYWHERE`, `When.ALWAYS`).
+
+
+
+
+== `hidden()`
+
+Title: @Hidden
+
+____
+
+Deprecated. For object members use link:./Property.html[@Property#hidden()] or link:./PropertyLayout.html[@PropertyLayout#hidden()], link:./Collection.html[@Collection#hidden()] or link:./CollectionLayout.html[@CollectionLayout#hidden()], and link:./ActionLayout.html[@ActionLayout#hidden()]. For domain servicesm use [@DomainService#nature()]
+
+____
+
+The `@Hidden` annotation indicates that the member (property, collection
+or action) to which it is applied should never be visible to the user.
+It can also be applied to service types (it has no effect if applied to
+entities or values).
+
+For example:
+
+[source]
+----
+public class Customer {
+ @Hidden
+ public int getInternalId() { ... }
+
+ @Hidden
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+Or, applied to a service:
+
+[source]
+----
+@Hidden
+public class EmailService {
+ public void sendEmail(...) { ... }
+ ...
+}
+----
+
+This annotation can also take a parameters indicating where and when it
+is to be hidden. For example:
+
+[source]
+----
+public class Customer {
+ @Hidden(when=When.ONCE_PERSISTED)
+ public int getInternalId() { ... }
+ ...
+}
+----
+
+would show the `Id` until the object has been saved, and then would hide
+it. And:
+
+[source]
+----
+public class Customer {
+ @Hidden(where=Where.ALL_TABLES)
+ public int getDateOfBirth() { ... }
+ ...
+}
+----
+
+would suppress the `dateOfBirth` property of a Customer from all tables.
+
+The acceptable values for the `where` parameter are:
+
+* `Where.ANYWHERE` +
++
+The member should be hidden everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The member should be hidden when displayed within an object form.
+For most viewers, this applies to property and collection members,
+not actions.
+
+* `Where.PARENTED_TABLES` +
++
+The member should be hidden when displayed as a column of a table
+within a parent object's collection. For most (all?) viewers, this
+will have meaning only if applied to a property member.
+
+* `Where.STANDALONE_TABLES` +
++
+The member should be hidden when displayed as a column of a table
+showing a standalone list of objects, for example as returned by a
+repository query. For most (all?) viewers, this will have meaning
+only if applied to a property member.
+
+* `Where.ALL_TABLES` +
++
+The member should be /hidden when displayed as a column of a table,
+either an object's * collection or a standalone list. This combines
+`PARENTED_TABLES` and `STANDALONE_TABLES`.
+
+* `Where.NOWHERE` +
++
+Acts as an override if a member would normally be hidden as a result
+of some other convention. For example, if a property is annotated
+with `@Title` <!--(see ?)-->, then normally this should be hidden from all
+tables. Additionally annotating with `@Hidden(where=Where.NOWHERE)`
+overrides this.
+
+The acceptable values for the `when` parameter are:
+
+* `When.ALWAYS` +
++
+The member should be hidden at all times.
+
+* `When.NEVER` +
++
+The member should never be hidden (unless disabled through some
+other mechanism, for example an imperative disableXxx() supporting
+method)..
+
+* `When.ONCE_PERSISTED` +
++
+The member should be visible for transient objects, but hidden for
+persisted objects.
+
+* `When.UNTIL_PERSISTED` +
++
+The member should be hidden for transient objects, but visible for
+persisted objects.
+
+By default the annotated property or action is always hidden (ie
+defaults to `Where.ANYWHERE`, `When.ALWAYS`).
+
+
+
+
+
+
+
+== `maxLength()`
+
+Title: @MaxLength
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#maxLength()] and link:./Parameter.html[@Parameter#maxLength()] .
+
+____
+
+The `@MaxLength` annotation indicates the maximum number of characters
+that the user may enter into a `String` property, or a `String`
+parameter in an action, or for a string-based value type. It is ignored
+if applied to any other type.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @MaxLength(30)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ ...
+}
+----
+
+Or, on an action parameter:
+
+[source]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @MaxLength(30)
+ @Named("First Name") String firstName
+ ,@MaxLength(30)
+ @Named("Last Name") String lastName) {
+ ...
+}
+----
+
+Or, for a value type:
+
+[source]
+----
+@Value(...)
+@MaxLength(30)
+public class CustomerFirstName {
+ ...
+}
+----
+
+If the model is being persisted to a relational database then
+`@MaxLength` should be specified for all `String` properties and action
+parameters.
+
+
+
+
+
+
+
+
+
+
+
+== `mustSatisfy()`
+
+Title: @MustSatisfy
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#mustSatisfy()] and link:./Parameter.html[@Parameter#mustSatisfy()].
+
+____
+
+The `@MustSatisfy` annotation allows validation to be applied to
+properties and parameters using an (implementation of a)
+`org.apache.isis.applib.spec.Specification` object.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @MustSatisfy(StartWithCapitalLetterSpecification.class)
+ public String getFirstName() { ... }
+ ...
+}
+----
+
+Or, on an action parameter:
+
+[source]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @MustSatisfy(StartWithCapitalLetterSpecification.class)
+ @Named("First Name") firstName
+ ,@MustSatisfy(StartWithCapitalLetterSpecification.class)
+ @Named("Last Name") lastName) {
+ ...
+ }
+ ...
+}
+----
+
+The `Specification` is consulted during validation, being passed the
+proposed value.
+
+An alternative to using `@MustSatisfy` is to define a custom value type (though this introduces additional mapping complexity for both viewers and objectstore).
+
+
+
+
+
+
+
+== `notPersisted()`
+
+Title: @NotPersisted
+
+The `@NotPersisted` annotation indicates that the property is not to be
+persisted.
+
+____
+
+*Note*
+
+In many cases the same thing can be achieved simply by providing the
+property with a 'getter' but no 'setter'.
+
+____
+
+For example:
+
+[source]
+----
+public class Order {
+
+ @NotPersisted
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
+
+ ...
+}
+----
+
+
+
+
+
+
+
+== `optionality()`
+
+Title: @Optional
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#optionality()] and link:./Parameter.html[@Parameter#optionality()].
+
+____
+
+By default, the system assumes that all properties of an object are
+required, and therefore will not let the user save a new object unless a
+value has been specified for each property. Similarly, by default, the
+system assumes that all parameters in an action are required and will
+not let the user execute that action unless values have been specified
+for each parameter.
+
+To indicate that either a property, or an action parameter, is optional,
+use the `@Optional` annotation.
+
+____
+
+*Note*
+
+The `@Optional`annotation has no meaning for a primitive property (or
+parameter) such as `int` - because primitives will always return a
+default value (e.g. zero). If optionality is required, then use the
+corresponding wrapper class (e.g. `java.lang.Integer`).
+
+____
+
+=== Making a property optional
+
+Annotate the getter to indicate that a property is `@Optional`. For
+example:
+
+[source]
+----
+public class Order {
+ public Product getProduct() { ... }
+
+ public java.util.Date getShipDate() { ... }
+ public void setShipDate(Date java.util.shipDate) { ... }
+
+ @Optional
+ public String getComments() { ... }
+ public void setComments(String comments) { ... }
+}
+----
+
+Here the `product` and `shipDate` properties are both required, but the
+`comments` property is optional.
+
+=== Making an action parameter optional
+
+To indicate that an action may be invoked without having to specify a
+value for a particular parameter, annotate with `@Optional`. For
+example:
+
+[source]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product
+ ,@Named("Quantity") int quantity
+ ,@Optional @Named("Special Instructions") String instr) {
+ ...
+ }
+ ...
+}
+----
+
+
+
+
+
+
+== `domainEvent()`
+
+Title: @PropertyInteraction
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#domainEvent()].
+
+____
+
+The `@PropertyInteraction` annotation applies to domain entity properties, allowing
+subscribers to optionally veto, validate or otherwise perform tasks before
+or after the property has been modified/cleared.
+
+Subscribers subscribe through the link:../services/event-bus-service.html[Event Bus Service] using Guava annotations.
+
+By default the event raised is `PropertyInteractionEvent.Default`. For example:
+
+[source]
+----
+public class ToDoItem {
+ ...
+ @PropertyInteraction
+ public LocalDate getDueBy() { ... }
+}
+----
+
+Optionally a subclass can be declared:
+
+[source]
+----
+public class ToDoItem {
+
+ public static class DueByChangedEvent extends PropertyInteractionEvent<ToDoItem, LocalDate> {
+ private static final long serialVersionUID = 1L;
+ public DueByChangedEvent(ToDoItem source, Identifier identifier, LocalDate oldValue, LocalDate newValue) {
+ super(source, identifier, oldValue, newValue);
+ }
+ }
+
+ @PropertyInteraction(ToDoItem.DueByChangedEvent)
+ public LocalDate getDueBy() { ... }
+
+}
+----
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using the Guava API.
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source]
+----
+@DomainService
+public class SomeSubscriber {
+
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(PropertyInteractionEvent ev) {
+
+ ...
+ }
+
+}
+----
+
+or can be fine-grained by subscribing to specific event subtypes:
+
+[source]
+----
+@DomainService
+public class SomeSubscriber {
+
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DueByChangedEvent ev) {
+
+ ...
+ }
+
+}
+----
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the property being modified
+* steps to perform after the property has been modified.
+
+The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
+
+[source]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(PropertyInteractionEvent ev) {
+
+ switch(ev.getPhase()) {
+ case HIDE:
+ ...
+ break;
+ case DISABLE:
+ ...
+ break;
+ case VALIDATE:
+ ...
+ break;
+ case EXECUTING:
+ ...
+ break;
+ case EXECUTED:
+ ...
+ break;
+ }
+}
+----
+
+Vetoing is performed by calling the appropriate method on the event:
+
+*
+
+To hide:
+
+ev.hide()
+
+*
+
+To disable:
+
+ev.disable("…");
+
+*
+
+To invalidate:
+
+ev.invalidate("…");
+
+It is also possible to abort the transaction during the executing or executed
+phases by throwing an exception. If the exception is a subtype of `RecoverableException`
+then the exception will be rendered as a user-friendly warning (eg Growl/toast)
+rather than an error.
+
+== Raising events programmatically.
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
+wrapping the target object using the link:../services/wrapper-factory.html[Wrapper Factory] service.
+
+== See also
+
+Interaction events can also be raised for link:./ActionInteraction.html[actions] and link:./CollectionInteraction.html[collections].
+
+
+
+
+
+
+== `regexPattern()`
+
+Title: @RegEx
+
+____
+
+Deprecated, use instead link:./Property.html[@Property#regex()] and link:./Parameter.html[@Parameter#regex()].
+
+____
+
+The `@RegEx` annotation may be applied to any string property, or to any
+parameter within an action method. It can also be applied to any
+string-based value type. It serves both to validate and potentially to
+normalise the format of the input. `@Regex` is therefore similar in use
+to `@Mask` <!--(see ?)--> but provides more flexibility.
+
+The syntax is:
+
+`@RegEx(validation = "regEx string",
+ format = "regEx string", caseSensitive =
+ <true|false>)`
+
+Only the first parameter is required; the `format` defaults to "no
+formatting", and `caseSensitive` defaults to false.
+
+For example, on a property:
+
+[source]
+----
+public class Customer {
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ public String getEmail() {}
+ ...
+}
+----
+
+Or, on a parameter:
+
+[source]
+----
+public class Customer {
+ public void updateEmail(
+ @RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+ @Named("Email") String email) {
+ ...
+ }
+ ...
+)
+----
+
+Or, on a value type:
+
+[source]
+----
+@Value(...)
+@RegEx(validation = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+")
+public class EmailAddress {
+ ...
+}
+----
+
+
+
+
+
+