1 /*
2 * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.properties.api.core.domain;
17
18 import java.io.Serializable;
19 import java.util.Locale;
20
21 /**
22 * Defines constraints on a property value and a description to the constraint
23 * that can be presented to the user.
24 *
25 * @param <T> the type of the property value.
26 */
27 public interface PropertyConstraint<T> extends Serializable
28 {
29 // ********************************* Fields *********************************
30
31 // --- constants ------------------------------------------------------------
32
33 // ****************************** Initializer *******************************
34
35 // ****************************** Inner Classes *****************************
36
37 // ********************************* Methods ********************************
38
39 // --- get&set --------------------------------------------------------------
40
41 /**
42 * Determines if the constraint is a check that evaluates if a property is
43 * present or not and fails if a value is not present.
44 *
45 * @return <code>true</code> if the constraint is a check for value presence,
46 * <code>false</code> if it is any regular constraint.
47 */
48 boolean isMandatoryConstraint();
49
50 /**
51 * Returns a localized description of the defined constraints.
52 *
53 * @param locale the locale to use to fetch a localized description.
54 * @return a localized description of the defined constraints.
55 */
56 String getDescription(Locale locale);
57
58 /**
59 * Returns a description of the defined constraints.
60 * <p>
61 * This is not the validation message that is displayed if the validation
62 * fails. This is a description of the constraints on a value that must be met
63 * to pass the validation process successfully. The description may be
64 * displayed to a user prior to request the input of a value.
65 * </p>
66 *
67 * @return a description of the defined constraints.
68 */
69 String getDescription();
70
71 /**
72 * Returns a localized description of the violation message adding the actual
73 * value.
74 *
75 * @param locale the locale to use for the message.
76 * @param actualValue the value that has violated the constraint.
77 * @return a localized description of violation message.
78 */
79 String getViolationMessage(Locale locale, Object actualValue);
80
81 // --- business -------------------------------------------------------------
82
83 /**
84 * Checks if the given value is valid for constraints in the default group.
85 *
86 * @param value the value to be checked.
87 * @return <code>true</code> if the {@code value} is valid, <code>false</code>
88 * otherwise.
89 */
90 boolean isValid(T value);
91
92 /**
93 * Checks if the given value is valid only if the constraint is in the given group.
94 *
95 * @param value the value to be checked.
96 * @param group the validation only takes place if this constraint is in this
97 * group or the argument is <code>null</code>.
98 * @return <code>true</code> if the {@code value} is valid, <code>false</code>
99 * otherwise.
100 */
101 boolean isValid(T value, Class<?> group);
102
103 /**
104 * Checks if the given value is valid for constraints in the default group.
105 *
106 * @param propertyDescriptor information about the name of the property to
107 * validate.
108 * @param value the value to be checked.
109 * @throws PropertyValidationException if the {@code value} is not valid.
110 */
111 void validate(final PropertyDescriptor propertyDescriptor, final T value)
112 throws PropertyValidationException;
113
114 /**
115 * Checks if the given value is valid.
116 *
117 * @param propertyDescriptor information about the name of the property to
118 * validate.
119 * @param value the value to be checked.
120 * @param group the validation only takes place if this constraint is in this
121 * group or the argument is <code>null</code>.
122 * @throws PropertyValidationException if the {@code value} is not valid.
123 */
124 void validate(PropertyDescriptor propertyDescriptor, T value, Class<?> group)
125 throws PropertyValidationException;
126
127 // --- object basics --------------------------------------------------------
128
129 }