001: /*
002: * Copyright (c) 2003-2007 JGoodies Karsten Lentzsch. All Rights Reserved.
003: *
004: * Redistribution and use in source and binary forms, with or without
005: * modification, are permitted provided that the following conditions are met:
006: *
007: * o Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * o Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * o Neither the name of JGoodies Karsten Lentzsch nor the names of
015: * its contributors may be used to endorse or promote products derived
016: * from this software without specific prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
020: * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
021: * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
022: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
023: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
024: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
025: * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
026: * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
027: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028: * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029: */
030:
031: package com.jgoodies.validation;
032:
033: import java.beans.PropertyChangeListener;
034:
035: /**
036: * Describes a model that holds a {@link ValidationResult} and provides bound
037: * read-only properties for the result, severity, error and messages state.
038: *
039: * @author Karsten Lentzsch
040: * @version $Revision: 1.5 $
041: *
042: * @see com.jgoodies.validation.util.DefaultValidationResultModel
043: *
044: * @since 1.1
045: */
046: public interface ValidationResultModel {
047:
048: /**
049: * The name of the bound property for the validation result.
050: *
051: * @see #getResult()
052: */
053: String PROPERTYNAME_RESULT = "result";
054:
055: /**
056: * The name of the bound property for the validation result severity.
057: *
058: * @see #getSeverity()
059: */
060: String PROPERTYNAME_SEVERITY = "severity";
061:
062: /**
063: * The name of the bound property that indicates whether there are errors.
064: *
065: * @see #hasErrors()
066: */
067: String PROPERTYNAME_ERRORS = "errors";
068:
069: /**
070: * The name of the bound property that indicates whether there are messages.
071: *
072: * @see #hasMessages()
073: */
074: String PROPERTYNAME_MESSAGES = "messages";
075:
076: // Accessors **************************************************************
077:
078: /**
079: * Returns this model's validation result which must be non-null.
080: *
081: * @return the current validation result
082: *
083: * @see #setResult(ValidationResult)
084: */
085: ValidationResult getResult();
086:
087: /**
088: * Sets a new non-null validation result and notifies all registered
089: * listeners, if the result changed. This is typically invoked at the end
090: * of the <code>#validate()</code> method.<p>
091: *
092: * Implementors shall throw a NullPointerException if the new result
093: * is null.
094: *
095: * @param newResult the validation result to be set
096: *
097: * @see #getResult()
098: */
099: void setResult(ValidationResult newResult);
100:
101: /**
102: * Looks up and returns the Severity of this model's validation result,
103: * one of <code>Severity.ERROR</code>, <code>Severity.WARNING</code>,
104: * or <code>Severity.OK</code>.
105: *
106: * @return the severity of this model's validation result
107: *
108: * @see #hasErrors()
109: * @see #hasMessages()
110: */
111: Severity getSeverity();
112:
113: /**
114: * Checks and answers whether this model's validation result has errors.
115: *
116: * @return true if the validation result has errors, false otherwise
117: *
118: * @see #getSeverity()
119: * @see #hasMessages()
120: */
121: boolean hasErrors();
122:
123: /**
124: * Checks and answers whether this model's validation result has messages.
125: *
126: * @return true if the validation result has messages, false otherwise
127: *
128: * @see #getSeverity()
129: * @see #hasErrors()
130: */
131: boolean hasMessages();
132:
133: // Managing Property Change Listeners *************************************
134:
135: /**
136: * Adds a PropertyChangeListener to the listener list. The listener is
137: * registered for all bound properties of this class.<p>
138: *
139: * If listener is null, no exception is thrown and no action is
140: * performed.
141: *
142: * @param listener the PropertyChangeListener to be added
143: *
144: * @see #removePropertyChangeListener(PropertyChangeListener)
145: * @see #removePropertyChangeListener(String, PropertyChangeListener)
146: * @see #addPropertyChangeListener(String, PropertyChangeListener)
147: * @see #getPropertyChangeListeners()
148: */
149: void addPropertyChangeListener(PropertyChangeListener listener);
150:
151: /**
152: * Removes a PropertyChangeListener from the listener list. This method
153: * should be used to remove PropertyChangeListeners that were registered
154: * for all bound properties of this class.<p>
155: *
156: * If listener is null, no exception is thrown and no action is performed.
157: *
158: * @param listener the PropertyChangeListener to be removed
159: *
160: * @see #addPropertyChangeListener(PropertyChangeListener)
161: * @see #addPropertyChangeListener(String, PropertyChangeListener)
162: * @see #removePropertyChangeListener(String, PropertyChangeListener)
163: * @see #getPropertyChangeListeners()
164: */
165: void removePropertyChangeListener(PropertyChangeListener listener);
166:
167: /**
168: * Adds a PropertyChangeListener to the listener list for a specific
169: * property. The specified property may be user-defined.<p>
170: *
171: * Note that if this Model is inheriting a bound property, then no event
172: * will be fired in response to a change in the inherited property.<p>
173: *
174: * If listener is null, no exception is thrown and no action is performed.
175: *
176: * @param propertyName one of the property names listed above
177: * @param listener the PropertyChangeListener to be added
178: *
179: * @see #removePropertyChangeListener(PropertyChangeListener)
180: * @see #removePropertyChangeListener(String, PropertyChangeListener)
181: * @see #addPropertyChangeListener(PropertyChangeListener)
182: * @see #getPropertyChangeListeners(String)
183: */
184: void addPropertyChangeListener(String propertyName,
185: PropertyChangeListener listener);
186:
187: /**
188: * Removes a PropertyChangeListener from the listener list for a specific
189: * property. This method should be used to remove PropertyChangeListeners
190: * that were registered for a specific bound property.<p>
191: *
192: * If listener is null, no exception is thrown and no action is performed.
193: *
194: * @param propertyName a valid property name
195: * @param listener the PropertyChangeListener to be removed
196: *
197: * @see #addPropertyChangeListener(PropertyChangeListener)
198: * @see #addPropertyChangeListener(String, PropertyChangeListener)
199: * @see #removePropertyChangeListener(PropertyChangeListener)
200: * @see #getPropertyChangeListeners(String)
201: */
202: void removePropertyChangeListener(String propertyName,
203: PropertyChangeListener listener);
204:
205: /**
206: * Returns an array of all the property change listeners
207: * registered on this component.
208: *
209: * @return all of this component's <code>PropertyChangeListener</code>s
210: * or an empty array if no property change
211: * listeners are currently registered
212: *
213: * @see #addPropertyChangeListener(PropertyChangeListener)
214: * @see #removePropertyChangeListener(PropertyChangeListener)
215: * @see #getPropertyChangeListeners(String)
216: * @see java.beans.PropertyChangeSupport#getPropertyChangeListeners()
217: */
218: PropertyChangeListener[] getPropertyChangeListeners();
219:
220: /**
221: * Returns an array of all the listeners which have been associated
222: * with the named property.
223: *
224: * @param propertyName the name of the property to lookup listeners
225: * @return all of the <code>PropertyChangeListeners</code> associated with
226: * the named property or an empty array if no listeners have
227: * been added
228: *
229: * @see #addPropertyChangeListener(String, PropertyChangeListener)
230: * @see #removePropertyChangeListener(String, PropertyChangeListener)
231: * @see #getPropertyChangeListeners()
232: */
233: PropertyChangeListener[] getPropertyChangeListeners(
234: String propertyName);
235:
236: }
|