The Java 1.5 reflector allows the domain modeller to define behaviourally complete domain objects, provide maximum feedback to the user, and control any interaction that may take place (rather than place that code in each and every user interface and back-end). This sections lists the explicit methods that are recognised by the standard reflector. All methods must be public to be recognised.
Methods that do not get matched with any of the listed rules are deemed to be action methods that we expect the user to invoke via the user interface. These are public methods, of the following format
public void <actionName>([<property type> param]...) public <type> <actionName>([<property type> param]...)
that are not used for fields, titles, or for controlling other methods. Essentially they are the methods left over from generating all other aspects of the class.
When such a method returns a reference the framework will attempt to display that object. If an action method returns null then nothing will be displayed.
public void addTo<PropertyName>(<collection element type> param)
Used in conjunction with a collection, the addTo method is called by the framework when the user adds an element to the collection. By providing this method in conjunction with a non-generic collection it will be limited to a specific type (rather than being used to store references of type Object). This behaviour is similar to that of the modify method for properties.
On a property
public <property type>[] choices<PropertyName>([<property type> param]) public List<property type> choices<PropertyName>([<property type> param])
Used in conjunction with a property, the choices method provides the user with a set of options for setting a property. This method is called when the user interface makes the options available, hence its return value can be based on the current state of the object. Note - this does not limit the state of the field, see the validate methods for a way to do that.
On parameters on an action
Either:
public Object[] choicesN<actionName>() public List<parameter type> choicesN<parameterNumber><actionName>()
where N is the 0-based parameter number.
Or:
public Object[] choices<actionName>([<parameter type> param]...) public List<parameter type> choices<parameterNumber><actionName>([<parameter type> param])
Complements an action method, or a specific paramter within an action.
The choices method provides a set of options for the parameters of an action. This method is called when the user interface prompts for the parameters from the user, so the options cannot depend on the state of any of the other parameters. Note - this does not limit the state of the parameter, see the validate methods for a way to do that.
For each parameter the array should contain either null, an array, or a collection.
public void clear<PropertyName>()
Used in conjunction with a property, the clear method is called when the user (rather than the framework) clears a reference field, or blanks (so there is no entry) a value field.
See also Link
public void created()
Life cycle method called by framework when an object is first created. This is the instance's logical creation. This method will not be called when the object is recreated during persistence or remoting.
For a property
public <parameter type> default<actionName>([<parameter type> param]...)
Complements a get/set method for a reference or value property.
Provides the default reference or value for a property to be set to when an object is first created, or the user asks for a property to be reset.
For parameters on an action
Either:
public Object[] defaultN<actionName>() public List<parameter type> defaultN<parameterNumber><actionName>()
where N is the 0-based parameter number.
Or:
public Object[] default<actionName>([<parameter type> param]...) public List<parameter type> default<parameterNumber><actionName>([<parameter type> param])
Complements an action method, or a specific parameter on an action method.
Provides the defaults that should be used for the parameters expected by an action method. The values should be provided as an array with the same number of elements as the number of parameters. Any parameter that does not have a default should have its corresponding element in the array set to null.
Deprecated but still supported; replaced by removed()
public void deleted()
Life cycle method called by framework when an object has just been removed from the persistent store. At this point the object will exist in memory, but no longer exist in the persistent store.
Deprecated but still supported; replaced by removing()
public void deleting()
Life cycle method called by framework when an object is just about to be removed from the persistent store. At this point the object still exists in the persistent store.
public String disable<PropertyName>([<property type> param]) public String disable<actionName>([<parameter type> param]...)
Complements a get/set method for a field, or an action method.
The disable dynamically controls whether a field is editable, or an action can be initiated. If a String object is returned the field or action is disabled and the string is made visible to user to inform them why it is disabled. If the method returns null then field or action remains enabled.
Value or reference property
public <property type> get<PropertyName>()
A standard JavaBean accessor/mutator pair will be recognised as a field for a value or reference. Values include Java primitives, Strings and Dates, and also the value types provided by the Naked Objects application library (see the section on recognised types).
If there is no mutator method then the field is flagged as being derived and will not be persisted or editable.
Collection property
A collection is picked up via an accessor method with the following signature. Java arrays, Vectors and Lists (including generic lists) are the only types that are recognised at the moment.
public <collection type> get<PropertyName>()
public String getId()
The getId method is used by service objects to provide an identity for a particular service type. This should be the same for all implementations of a specific service allowing them to be swapped for one another.
public boolean hide<PropertyName>([<property type> param]) public boolean hide<actionName>([<parameter type> param]...)
Complements a get/set method for a field, or an action method.
The hide method allows a property or action to be dynamically hidden from the user. This is typically used for security reasons, such as hiding a field once it is set up. Returning true makes the property or action invisible.
public String iconName()
The iconName is used to over-ride the framework's default mechanism for determining the icon to display based on the class name. The name returned by this method should be simply a name and not a filepath: it should not have an file extension. The framework will look for an acceptable type of image using this name, deriving possible filenames from it. See the section on images for more information.
public void loaded()
Life cycle method called by framework when an object has just been loaded in from the persistent store. At this point the object has it's correct persisted state.
public void loading()
Life cycle method called by framework when an object is just about to be loaded from the persistent store. At this point the object exists in memory but has not had its state restored.
public void modify<PropertyName>(<property type> param)
Complements a property.
The modify method is called when the user (rather than the framework) sets a reference or value field. This is typically used to initialise an association (where an association is combination of references, such as a back link), or to trigger other behaviours such as adding the new value to a total.
See also Link.
Replaces saved()
public void persisted()
Life cycle method called by framework when a transient object has just been added to the persistent store. At this point the object exists in the persistent store.
Replaces saving()
public void persisting()
Life cycle method called by framework when a transient object is just about to be added to the persistent store. At this point the object exists only in memory and not in the persistent store.
Replaces deleted()
public void removed()
Life cycle method called by framework when an object has just been removed from the persistent store. At this point the object will exist in memory, but no longer exist in the persistent store.
Replaces deleting()
public void removing()
Life cycle method called by framework when an object is just about to be removed from the persistent store. At this point the object still exists in the persistent store.
public void removeFrom<PropertyName>(<property type> param)
Complements a collection.
The removeFrom method is called by the framework when the user removes an element from the collection. By providing this method in conjunction with a non-generic collection interactions with that collection become limited to a specific type (rather than being used to store references of type Object). This signature is similar to the clear method for properties.
Deprecated but still supported; replaced by persisted()
public void saved()
Life cycle method called by framework when a transient object has just been added to the persistent store. At this point the object exists in the persistent store..
Deprecated but still supported; replaced by persisting()
public void saving()
Life cycle method called by framework when a transient object is just about to be added to the persistent store. At this point the object exists only in memory and not in the persistent store.
public void set<PropertyName>(<property type> param)
Complements a get method.
The set method is called when the property is changed, either by the user or the framework. As the framework calls the same method when recreating the object from persistent data it is important to avoid doing any work in the set method other than setting up the property variable. A typical set method would be:
private String name;
public void setName(String name) {
this.name = name;
}
public String toString()
The toString method is used to get a title for the object. If the toString method cannot serve as the title, because it is being used for alternative purposes (such as debugging) then you may define a title method instead (below).
public String title()
If a title method is defined then the framework will use this in preference to the toString method for displaying the object's title.
public void updated()
Life cycle method called by framework when a modified persistent object has just been saved to the persistent store. At this point the object's state in the persistent store will be in its new state.
public void updating()
Life cycle method called by framework when a persistent object has just been modified and is about to be saved to the persistent store. At this point the object's state in the persistent store will still be in its pre-modified state.
Ensure value or reference is valid
public String validate<PropertyName>(<property type> param)
Complements a get/set method for a value or reference property.
This validate method is used to check the value/reference that is to be used to set a property. Using such a mechanism the programmer can guarantee that a field never becomes invalid. If a String object is returned the value/reference is consider to be invalid and the field will not be set. The string itself will then be made visible to the user to inform them why it is invalid. If the method returns null then property will be set, that is, its set or modify method will be called with the same parameter.
Ensure collection can have an element added or removed
public String validateAddTo<PropertyName>(<property type> param) public String validateRemoveFrom<PropertyName>(<property type> param)
Complements a get method for a collection property.
This validate method is used to check that the specified object can be added to or removed from a collection. Using such a mechanism the programmer can guarantee that the collection never becomes invalid. If a String object is returned then adding/removing the specified object is not valid and the collection will not be changed. The string itself will then be made visible to the user to inform them why changing the collection with the object would be invalid. If the method returns null then the object will be added to/removed from the collection, that is, from the collection object directly if there is no addTo/removeFrom method, or via a call to the addTo/removeFrom method, with the same parameter, if they do exist.
Ensure it is valid to invoke an action
public String validate<actionName>([<parameter type> param]...)
Complements an action method.
This validate method is used to check that the actions parameters are all valid and that the action method can be safely invoked, that is, if it is invoked that it will not fail. If a String object is returned then the action should not be invoked. The string itself will then be made visible to the user to inform them why the method cannot be invoked. If the method returns null then the action method will be invoked with the same set of parameters.
Ensure object is in a valid state to be saved
A validate() method may be added to provided validation at object level - prior to making an object persistent.
public String validate()
This is particularly useful for validating fields in relation to each other, as in the following example:
public class Booking {
private Date fromDate;
public Date getFromDate() {...}
public void setFromDate(Date d) {...}
private Date toDate;
public Date getToDate() {...}
public void setToDate(Date d) {...}
public String validate() {
if (fromDate > toDate) {
return "From Date cannot be after To Date";
}
return null;
}
...
}
This will prevent the user from saving a transient Booking where the From Date falls after the To Date. Note that in this example, the two date properties could also have their own individual validate methods - for example in order to test that each date was after today.
At the time of writing, the validate method is called only when the object is first saved, not when it is subsequently updated. For validation of subsequent updates, it is necessary to build the validation logic into the individual property validation methods, though these could delegate to a common validate method.