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: /**
034: * Describes validation messages as used by the JGoodies Validation framework.
035: * All validation messages provide a formatted text ({@link #formattedText()})
036: * and are categorized into types of different severity (@link #severity()}).
037: * Validation messages are collected during the validation process and
038: * are held by instances of {@link com.jgoodies.validation.ValidationResult}.<p>
039: *
040: * This class has been designed to be decoupled from user interface components
041: * (views) that present and edit the validated data. The design goal is to be
042: * able to use the same validation mechanism on the server side, in the domain
043: * layer, in a view-less model layer, and in the presentation layer.
044: * And we want to ensure that multiple views can present the same model,
045: * and so we typically don't store a view in the validation message.
046: * On the other hand we want to detect which validation messages belongs
047: * to a given user interface component, for example to let the component
048: * paint a warning indication.
049: * This association between message and view is established by the message key
050: * that can be shared between messages, validators, views, and other parties.
051: * It can be requested using the {@link #key()} method. The association is
052: * checked using <code>#equals</code>; implementors that use rich objects
053: * as keys may consider overriding <code>#equals</code>.<p>
054: *
055: * For example, a validator validates an address object and reports
056: * that the zip code is invalid. You may choose the association key
057: * as <code>"address.zipCode"</code>. All views that present the zip code
058: * can now check and verify whether a validation result contains messages
059: * with this key and may paint a special warning background.
060: * If the validated data contains two different address objects, let's say
061: * a shipping address and a physical address, the address validator may
062: * add a prefix and create keys like <code>physical.address.zipCode</code>
063: * and <code>shipping.address.zipCode</code>. A view can now differentiate
064: * between the two zip codes.<p>
065: *
066: * We've choosen to let the <code>ValidationMessage</code> check whether
067: * an association key matches or not. This way, an implementation of this
068: * interface can choose to provide special checks. The default behavior
069: * in class {@link com.jgoodies.validation.message.AbstractValidationMessage}
070: * just checks whether a given association key equals a stored key.<p>
071: *
072: * Implementors may hold additional objects, for example the validation target,
073: * a description of the target, or a description of the validated property.
074: * Implementors are encouraged to implement <code>#equals</code> and
075: * <code>#hashCode</code> to prevent unnecessary change notifications
076: * for the <em>result</em> property when a ValidationResultModel
077: * gets a new ValidationResult. See for example the implementation of method
078: * {@link com.jgoodies.validation.message.PropertyValidationMessage#equals(Object)}.
079: *
080: * @author Karsten Lentzsch
081: * @version $Revision: 1.5 $
082: *
083: * @see com.jgoodies.validation.ValidationResult
084: * @see com.jgoodies.validation.message.AbstractValidationMessage
085: */
086: public interface ValidationMessage {
087:
088: /**
089: * Returns this message's severity: error or warning.
090: * <code>Severity.OK</code> is not allowed as the severity
091: * of a single message, but OK is a valid ValidationResult severity.
092: *
093: * @return this message's severity: error or warning
094: */
095: Severity severity();
096:
097: /**
098: * Returns a formatted text that describes the validation issue
099: * this message represents.
100: *
101: * @return the message as a formatted text
102: */
103: String formattedText();
104:
105: /**
106: * Returns this message's association key that can be used to model
107: * a loose coupling between validation messages and views that present
108: * the validated data. See the class comment for more information
109: * about this relation.
110: *
111: * @return this message's association key
112: */
113: Object key();
114:
115: }
|