001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: Constrained.java 3717 2007-04-12 18:01:39Z gbevin $
007: */
008: package com.uwyn.rife.site;
009:
010: import java.util.Collection;
011:
012: /**
013: * This interface defines methods for bean-centric constraining of data
014: * entities.
015: * <p>A constraint describes additional information about a data entity. Its
016: * main purpose is to alter the default behaviour of a data type and to
017: * clearly set the accepted limits. The meta-data that's provided through
018: * constraints can be used elsewhere to gather more information about how to
019: * correctly integrate the indicated data limits.
020: * <p>For example, a constraint specifies that a certain text's length is
021: * limited to 30 characters, parts of the system can query this information
022: * and act accordingly:
023: * <ul>
024: * <li>a HTML form builder can create a field that doesn't allow the entry of
025: * longer text,
026: * <li>a SQL query builder can limit the size of the column in which the text
027: * will stored when the table creation SQL is generated,
028: * <li>a validation system can check if the text isn't longer than 30
029: * characters and provide appropriate information when the length is exceeded.
030: * </ul>
031: * <p>There are two types of constraints:
032: * <ul>
033: * <li>those that are related to the entire bean (<code>ConstrainedBean</code>
034: * constraints)
035: * <li>those that only apply to a single property (<code>ConstrainedProperty</code>
036: * constraints)
037: * </ul>
038: *
039: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
040: * @see ConstrainedBean
041: * @see ConstrainedProperty
042: * @version $Revision: 3717 $
043: * @since 1.0
044: */
045: public interface Constrained<B extends ConstrainedBean, P extends ConstrainedProperty> {
046: /**
047: * Add a new constrained bean.
048: * <p>
049: * When several constrained beans are added, they are merged at
050: * constraint-level. This means for instance that all previous unique
051: * constraints will be replaced by those of the new constrained bean, they
052: * will not be combined.
053: *
054: * @param constrainedBean the <code>ConstrainedBean</code> instance
055: * that has to be added
056: * @see ConstrainedBean
057: * @since 1.0
058: */
059: public void addConstraint(B constrainedBean);
060:
061: /**
062: * Add a new constrained property.
063: * <p>
064: * When several of the same constrained properties are added, they are
065: * merged at constraint-level. This means for instance that a previous
066: * inList constraint will be replaced by the one of the new constrained
067: * bean, they will not be combined.
068: *
069: * @param constrainedProperty the <code>ConstrainedProperty</code>
070: * instance that has to be added
071: * @see ConstrainedProperty
072: * @since 1.0
073: */
074: public void addConstraint(P constrainedProperty);
075:
076: /**
077: * Retrieves the constrained bean that has been set for this
078: * <code>Constrained</code> instance.
079: *
080: * @return the requested <code>ConstrainedBean; or </code>
081: * <p><code>null</code> if no <code>ConstrainedBean</code> is
082: * available.
083: * @see ConstrainedProperty
084: * @since 1.0
085: */
086: public B getConstrainedBean();
087:
088: /**
089: * Returns a collection with all the constrained properties that have
090: * been registered.
091: *
092: * @return A <code>Collection</code> with all the
093: * <code>ConstrainedProperty</code> objects that are registered. If no
094: * constrained properties are available, an empty collection will be
095: * returned, not <code>null</code>.
096: * @see ConstrainedProperty
097: * @since 1.0
098: */
099: public Collection<P> getConstrainedProperties();
100:
101: /**
102: * Indicates whether this constrained bean contains a particular constraint
103: * on at least one of its properties.
104: *
105: * @return <code>true</code> if this constraint is present on at least one
106: * of the properties; or
107: * <p><code>false</code> otherwise
108: * @see ConstrainedProperty
109: * @since 1.6
110: */
111: public boolean hasPropertyConstraint(String name);
112:
113: /**
114: * Retrieve a registered <code>ConstrainedProperty</code> according to
115: * its name.
116: *
117: * @param propertyName the name of the
118: * <code>ConstrainedProperty</code> that has to be retrieved
119: * @return the requested <code>ConstrainedProperty; or </code>
120: * <p><code>null</code> if no such <code>ConstrainedProperty</code> is
121: * available.
122: * @see ConstrainedProperty
123: * @since 1.0
124: */
125: public P getConstrainedProperty(String propertyName);
126: }
|