2.2.1 Property
@Mask
The @Mask annotation may be applied to any property, or to any parameter within an action
method, that is a value type (i.e. that allows the user to type in text as input). The mask serves
to validate, and potentially to normalise, the format of the input. The characters that can be
used are based on Swing's MaskFormatter, Java's SimpleDateFormat and also Microsoft's
MaskedEdit control. When applying a mask to a value property, the annotation should be
applied to the 'getter'. For example:
public class Email {
private String telNo;
@Mask("(NNN)NNN-NNNN")
public String getTelephoneNumber() {...}
public void setTelephoneNumber(String telNo) {...}
...
}
When applying a mask to a value parameter within an action method, the annotation should be
applied 'in-line' (i.e. immediately before that parameter). For example:
public void newContact(
@Named("Contact Name")
String contactName,
@Named("Telephone Number")
@Mask("(NNN)NNN-NNNN")
String telNo) {}
@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. It is ignored if applied to a
property or parameter of any other type. For example:
public class Customer {
@MaxLength(30)
public String getFirstName() { ... }
public void setFirstName(String firstName) { ... }
...
}
If the model is being persisted on a relational database then @MaxLength should be specified
for all String properties and action parameters.
@NotPersisted
When applied at object level, transient instances of this class may be created but may not
be persisted. The viewer will not provide the user with an option to 'save' the object, and
attempting to persist such an object programmatically would be an error. For example:
@NotPersisted
public class InputForm {
// members and actions here
}
When applied at property level, this indicates that the property is not to be persisted. Note that
in many cases the same thing could be achieved by providing the property with a 'getter' but no
'setter'. For example:
public class Order {
private Order previousOrder;
@NotPersisted
public Order getPreviousOrder() {...}
public void setPreviousOrder(Order previousOrder) {...}
// rest of code
}
@MultiLine
The @MultiLine annotation provides information about the carriage returns in a String
property or action parameter. The annotation indicates that: - the String property or parameter
may contain carriage returns, and
- (optionally) the typical number of such carriage returns, and
- (optionally) that the text should be wrapped (the default is that text is not wrapped).
Reference 96
Draft (reference/recognised-annotations.xml) Recognised Annotations
This may be used by the viewing mechanism to render the property as a multi-line textbox
(or text-editor when changes are permitted), with appropriate wrapping and/or scrollbars. The
syntax is:
@MultiLine([numberOfLines=<typicalNumberOfCRs>]
[,preventWrapping=<false|true>])
For example:
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:
public class Email {
@MultiLine(numberOfLines=20,preventWrapping=false)
public String getBody() { ... }
public void setBody(String body) { ... }
...
}
Here the body will be (likely be) displayed in a text area of 20 rows, with wrapping. If this
annotation is combined with the @TypicalLength, then the likely width of the text area in the
user interface will be the: @TypicalLength @MultiLine. For example:
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.
@Optional
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 indiciate that
either a property, or an action parameter, is optional, use the @Optional annotation.
Making a property optional
To indicate that a property is optional (i.e. that the user may save the object without necessarily
specifying a value for this property), use the @Optional annotation immediately before the
declaration of that property. For example:
public class Order {
public Product getProduct() { ... }
public java.util.Date getShipDate() { ... }
Reference 97
Draft (reference/recognised-annotations.xml) Recognised Annotations
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
paramater, the @Optional annotation should be used in-line i.e. immediately before the
declaration of that parameter. For example:
public class Customer {
public Order placeOrder(
@Optional
Product product,
@Named("Quantity")
int quantity) {
Order order = new Order();
order.modifyCustomer(this);
order.modifyProduct(
product!=null ? product : productOfLastOrder());
order.setQuantity(quantity);
return order;
}
private Product productOfLastOrder() { ... }
// other members omitted
}
@RegEx
The @RegEx annotation may be applied to any property, or to any parameter within an action
method, that is a value type (i.e. that allows the user to type in text as input). It serves both to
validate and potentially to normalise the format of the input. @Regex is therefore similar in use
to @Mask but provides more flexibility. The syntax is:
Reference 98
Draft (reference/recognised-annotations.xml) Recognised Annotations
@RegEx(validation = <regEx string>, format = <regEx string>,
caseSensitive = <true|false>)
The first parameter is required; the format defaults to 'no formatting'; caseSensitive defaults to
false. When applying Regex to a value property, the annotation should be applied to the 'getter'.
For example:
private String email;
@RegEx(validation = "(\w+\.)*\w+@(\w+\.)+[A-Za-z]+")
public String getEmail() {}
public void setEmail(String email) {}
When applying a RegEx expression to a value parameter within an action method, the
annotation should precede that parameter:
public void newContact(
@Named("Contact Name")
String contactName,
@Named("Email")
@RegEx(validation = "(\w+\.)*\w+@(\w+\.)+[A-Za-z]+")
String email) {}
@TypeOf
The @TypeOf annotation is used to specify the type of element a collection is able to hold. The
user will then only be able to add objects of this type to the collection. For example:
@TypeOf(Customer.class)
public List getCustomer() {
return customers;
}
@TypicalLength
The @TypicalLength annotation indicates the typical length of a String property or  String parameter in an action. This may be used by the viewing mechanism to determine the  space that should be given to that property or parameter in the appropriate view. If the  @TypicalLength is less than the @MaxLength then the text field will scroll as required. If the  typical length is the same as the @MaxLength 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:
public class Customer {
   @MaxLength(30)
   
@TypicalLength(20)
       
public String getFirstName() { ... }
   public void setFirstName(String firstName) { ... }
}