001    /*******************************************************************************
002     * Portions created by Sebastian Thomschke are copyright (c) 2005-2011 Sebastian
003     * Thomschke.
004     * 
005     * All Rights Reserved. This program and the accompanying materials
006     * are made available under the terms of the Eclipse Public License v1.0
007     * which accompanies this distribution, and is available at
008     * http://www.eclipse.org/legal/epl-v10.html
009     * 
010     * Contributors:
011     *     Sebastian Thomschke - initial implementation.
012     *******************************************************************************/
013    package net.sf.oval;
014    
015    import java.io.Serializable;
016    import java.util.Map;
017    
018    import net.sf.oval.context.OValContext;
019    import net.sf.oval.exception.OValException;
020    
021    /**
022     * interface for classes that can check/validate if a constraint is satisfied
023     * 
024     * @author Sebastian Thomschke
025     */
026    public interface Check extends Serializable
027    {
028            /**
029             * <p>In case the constraint is declared for an array, collection or map this controls how the constraint is applied to it and it's child objects.
030             * 
031             * <p><b>Default:</b> ConstraintTarget.CONTAINER
032             * 
033             * <p><b>Note:</b> This setting is ignored for object types other than array, map and collection.
034             */
035            ConstraintTarget[] getAppliesTo();
036    
037            /**
038             * @return Returns the context where the constraint was declared.
039             * 
040             * @see net.sf.oval.context.ClassContext
041             * @see net.sf.oval.context.ConstraintSetContext
042             * @see net.sf.oval.context.FieldContext
043             * @see net.sf.oval.context.MethodEntryContext
044             * @see net.sf.oval.context.MethodExitContext
045             * @see net.sf.oval.context.MethodParameterContext
046             * @see net.sf.oval.context.MethodReturnValueContext
047             */
048            OValContext getContext();
049    
050            /**
051             * @return the error code that will be used in a corresponding ConstraintViolation object
052             */
053            String getErrorCode();
054    
055            /** 
056             * gets the default message that is displayed if a corresponding message key
057             * is not found in the messages properties file
058             * <br>
059             * default processed place holders are:
060             * <ul>
061             * <li>{context} => specifies which getter, method parameter or field was validated
062             * <li>{invalidValue} => string representation of the validated value
063             * </ul>
064             */
065            String getMessage();
066    
067            /**
068             * values that are used to fill place holders when rendering the error message.
069             * A key "min" with a value "4" will replace the place holder {min} in an error message
070             * like "Value cannot be smaller than {min}" with the string "4".
071             */
072            Map<String, ? extends Serializable> getMessageVariables();
073    
074            /**
075             * @return the profiles, may return null
076             */
077            String[] getProfiles();
078    
079            /**
080             * @return the severity
081             */
082            int getSeverity();
083    
084            /**
085             * An expression to specify where in the object graph relative from this object the expression
086             * should be applied.
087             * <p>
088             * Examples:
089             * <li>"owner" would apply this constraint to the current object's property <code>owner</code>
090             * <li>"owner.id" would apply this constraint to the current object's <code>owner</code>'s property <code>id</code>
091             * <li>"jxpath:owner/id" would use the JXPath implementation to traverse the object graph to locate the object where this constraint should be applied.
092             */
093            String getTarget();
094    
095            /**
096             * Formula returning <code>true</code> if this constraint shall be evaluated and
097             * <code>false</code> if it shall be ignored for the current validation.
098             * <p>
099             * <b>Important:</b> The formula must be prefixed with the name of the scripting language that is used.
100             * E.g. <code>groovy:_this.amount > 10</code>
101             * <p>
102             * Available context variables are:<br>
103             * <b>_this</b> -&gt; the validated bean<br>
104             * <b>_value</b> -&gt; the value to validate (e.g. the field value, parameter value, method return value,
105             *    or the validated bean for object level constraints)
106             *    
107             * @return the formula
108             */
109            String getWhen();
110    
111            /**
112             * 
113             * @param validatedObject the object/bean to validate the value against, for static fields or methods this is the class
114             * @param valueToValidate the value to validate, may be null when validating pre conditions for static methods
115             * @param validator the calling validator
116             * @return <code>true</code> if this check is active and must be satisfied
117             */
118            boolean isActive(Object validatedObject, Object valueToValidate, Validator validator);
119    
120            /**
121             * This method implements the validation logic
122             * 
123             * @param validatedObject the object/bean to validate the value against, for static fields or methods this is the class
124             * @param valueToValidate the value to validate, may be null when validating pre conditions for static methods
125             * @param context the validation context (e.g. a field, a constructor parameter or a method parameter)
126             * @param validator the calling validator
127             * @return true if the value satisfies the checked constraint
128             */
129            boolean isSatisfied(Object validatedObject, Object valueToValidate, OValContext context, Validator validator)
130                            throws OValException;
131    
132            /**
133             * @param target the constraint target to set
134             */
135            void setAppliesTo(ConstraintTarget... target);
136    
137            /**
138             * @param context the context to set
139             */
140            void setContext(OValContext context);
141    
142            /**
143             * @param errorCode the error code to set
144             */
145            void setErrorCode(String errorCode);
146    
147            /**
148             * sets the default message that is displayed if a corresponding message key
149             * is not found in the messages properties file
150             * 
151             * <br>
152             * default processed place holders are:
153             * <ul>
154             * <li>{context} => specifies which getter, method parameter or field was validated
155             * <li>{invalidValue} => string representation of the validated value
156             * </ul>
157             */
158            void setMessage(String message);
159    
160            /**
161             * @param profiles the profiles to set
162             */
163            void setProfiles(String... profiles);
164    
165            /**
166             * @param severity the severity to set
167             */
168            void setSeverity(int severity);
169    
170            /**
171             * Sets an expression to specify where in the object graph relative from this object the expression
172             * should be applied.
173             * <p>
174             * Examples:
175             * <li>"owner" would apply this constraint to the current object's property <code>owner</code>
176             * <li>"owner.id" would apply this constraint to the current object's <code>owner</code>'s property <code>id</code>
177             * <li>"jxpath:owner/id" would use the JXPath implementation to traverse the object graph to locate the object where this constraint should be applied.
178             */
179            void setTarget(String target);
180    
181            /**
182             * Sets the formula returning <code>true</code> if this constraint shall be evaluated and
183             * <code>false</code> if it shall be ignored for the current validation.
184             * <p>
185             * <b>Important:</b> The formula must be prefixed with the name of the scripting language that is used.
186             * E.g. <code>groovy:_this.amount > 10</code>
187             * <p>
188             * Available context variables are:<br>
189             * <b>_this</b> -&gt; the validated bean<br>
190             * <b>_value</b> -&gt; the value to validate (e.g. the field value, parameter value, method return value,
191             *    or the validated bean for object level constraints)
192             *  
193             * @param when formula calculating if this check is active
194             */
195            void setWhen(String when);
196    }