| | {anchor:top} |
| | * [What are constraints?|#1] |
| | * [Constrained properties|#2] |
| | * [Static constraints|#3] |
| | * [Dynamic constraints|#4] |
| | |
| | ---- |
| | |
| | Many parts of an application benefit a lot from an easy way to obtain the type, the accepted limits, and the behavioural patterns of a data entity. In RIFE this has now been centralized into a bean. You have the possibility to add a collection of constraints to its properties and retrieve this information later on. This neatly centralizes the addition of this meta-data. |
| | |
| | {anchor:1} |
| | h2. What are constraints? |
| | |
| | The main purpose of a constraint is to alter the default behaviour of a data type and to clearly set the accepted limits. The meta-data that's provided through constraints can be used elsewhere to gather more information about how to correctly integrate the indicated data limits. |
| | |
| | For example, a constraint specifies that a certain text's length is limited to 30 characters, parts of the system can query this information and act accordingly: |
| | |
| | * a HTML form builder can create a field that doesn't allow the entry of longer text, |
| | * a SQL query builder can limit the size of the column in which the text will stored when the table creation SQL is generated, |
| | * a validation system can check if the text isn't longer than 30 characters and provide appropriate information when the length is exceeded. |
| | |
| | Several types of constraints will be available, but currently only constrained bean properties are supported through the ConstrainedProperty class.. |
| | |
| | [\[top\]|#top] |
| | |
| | {anchor:2} |
| | h2. Constrained properties |
| | |
| | A {{ConstrainedProperty}} object makes it possible to easily define all constraints for a named property of a bean. |
| | |
| | The property name refers to the actual name of the bean property. However, this sometimes doesn't correspond to its conceptual usage. It can be handy to receive constraint violation reports with another conceptual name: the subject name. Notice that this corresponds to the subject that is used in a {{ValidationError}}. If no subject name is specified, the property name will be used instead. |
| | |
| | It's possible to add constraints to a {{ConstrainedProperty}} instance through regular setters, but chainable setters are also available to make it possible to easily define a series of constraints, for example: |
| | |
| | {code:java} |
| | ConstrainedProperty constrained = new ConstrainedProperty("password"); |
| | constrained |
| | .maxLength(8) |
| | .notNull(true); |
| | {code} |
| | |
| | [\[top\]|#top] |
| | |
| | {anchor:3} |
| | h2. Static constraints |
| | |
| | Constrained properties are typically added to a {{Constrained}} bean in its constructor or in a dedicated {{activateMetaData()}} method when extending the {{MetaData}} class. This method is the preferred approach since it will only be called the first time any validation-related method is called on a particular bean instance and thus not at every instantiation of the bean. Both approaches define static constraints that will be set for each and every instance of the bean, for example the following {{Credentials}} class extends {{Validation}} which contains a concrete implementation of the {{Constrained}} interface: |
| | |
| | {code:java} |
| | public class Credentials extends MetaData<ConstrainedBean, ConstrainedProperty> |
| | { |
| | private String mLogin = null; |
| | private String mPassword = null; |
| | private String mLanguage = null; |
| | |
| | public Credentials() |
| | { |
| | } |
| | |
| | public void activateMetaData() |
| | { |
| | addConstraint(new ConstrainedProperty("login").maxLength(6).notNull(true)); |
| | addConstraint(new ConstrainedProperty("password").maxLength(8).notNull(true)); |
| | addConstraint(new ConstrainedProperty("language").notNull(true)); |
| | } |
| | |
| | public void setLogin(String login) { mLogin = login; } |
| | public String getLogin() { return mLogin; } |
| | public void setPassword(String password) { mPassword = password; } |
| | public String getPassword() { return mPassword; } |
| | public void setLanguage(String language) { mLanguage = language; } |
| | public String getLanguage() { return mLanguage; } |
| | } |
| | {code} |
| | |
| | [\[top\]|#top] |
| | |
| | {anchor:4} |
| | h2. Dynamic constraints |
| | |
| | It's also possible however to add constraints to a single bean instance whenever they cannot be determined beforehand. These are then dynamic constraints which can be populated at runtime, for example: |
| | |
| | {code:java} |
| | Credentials credentials = new Credentials(); |
| | credentials.addConstraint(new ConstrainedProperty("language").inList(new String[] {"nl", "fr", "en"})); |
| | {code} |
| | |
| | To retrieve constrained properties after they have been added, you can use the {{getConstrainedProperties()}} and {{getConstrainedProperty(String propertyName)}} methods. |
| | |
| | {tip:title=Meta data merging} |
| | If you don't want to pollute your model beans with RIFE-specific imports or behavior, consider using the [Meta data merging] facility to externalize your constraints. |
| | | {tip} |
| | |
| | [\[top\]|#top] |
