1 /**
2 * Copyright 2005-2012 The Kuali Foundation
3 *
4 * Licensed under the Educational Community 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.opensource.org/licenses/ecl2.php
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 org.kuali.rice.krad.datadictionary.validation;
17
18 import org.kuali.rice.krad.datadictionary.exception.AttributeValidationException;
19 import org.kuali.rice.krad.datadictionary.validation.capability.Constrainable;
20
21 import java.util.List;
22
23 /**
24 * AttributeValueReader defines classes that encapsulate access to both dictionary metadata and object field values
25 *
26 * <p>For example, by reflection
27 * and introspection, for the purpose of performing validation against constraints defined in the
28 * DictionaryValidationService implementation.</p>
29 *
30 * <p>Practically speaking, this interface should only need to be implemented by a small number of classes. The two
31 * major use cases are for
32 * <ol>
33 * <li> a dictionary object with members</li>
34 * <li> a specific member of a dictionary object</li>
35 * </ol>
36 * </p>
37 * <p>
38 * In the first case, implementing classes should provide access to all underlying members of the object via reflection
39 * or some other mechanism.
40 * In the second case, implementing classes only need to provide access to the value associated with that specific
41 * member, and constraints
42 * requiring access to additional members will be skipped.</p>
43 *
44 * @author Kuali Rice Team (rice.collab@kuali.org)
45 * @since 1.1
46 */
47 public interface AttributeValueReader {
48
49 /**
50 * acts as an accessor for the attribute name that is currently being processed by the DictionaryValidationService
51 * implementation
52 *
53 * @return the current attribute name being processed
54 */
55 public String getAttributeName();
56
57 /**
58 * provides access to the constrainable attribute definition of a specific attribute name
59 *
60 * <p>If the value of the metadata
61 * associated with the object field does not implement constrainable, or if no metadata is associated with this
62 * object
63 * field,
64 * then null should be returned.</p>
65 *
66 * @param attributeName - the name of the attribute/field whose metadata is being requested
67 * @return dictionary metadata object implementing some constrainable capability
68 */
69 public Constrainable getDefinition(String attributeName);
70
71 /**
72 * gets a list of all constrainable dictionary metadata definitions for attributes or fields encapsulated by this
73 * object
74 *
75 * @return a list of constrainable definitions
76 */
77 public List<Constrainable> getDefinitions();
78
79 /**
80 * gets the dictionary metadata associated with an object (its "entry" in the dictionary)
81 *
82 * <p>It can also be constrainable, in which case the object
83 * value itself can be validated against one or more constraints. If the specific entry for the dictionary object
84 * encapsulated by this
85 * reader is not constrainable, or if no entry exists for this dictionary object, or no dictionary object is being
86 * encapsulted, then
87 * null should be returned.
88 * </p>
89 *
90 * @return the constrainable dictionary entry metadata for this object, or null
91 */
92 public Constrainable getEntry();
93
94 /**
95 * gets the entry name for the purposes of correct error look up
96 *
97 * <p>Errors are generally found by entry name + attribute name + error key</p>
98 *
99 * @return the name that the data dictionary uses to store metadata about this object (not its attributes)
100 */
101 public String getEntryName();
102
103 /**
104 * looks up a label for a specific attribute name
105 *
106 * @param attributeName - the name of attribute
107 * @return some descriptive label that can be exposed to the end user for error messages
108 */
109 public String getLabel(String attributeName);
110
111 /**
112 * gets the underlying object itself (not the field/attribute value, but the object)
113 *
114 * @return the object that is being encapsulated by this reader, or null if no object is being encapsulated
115 */
116 public Object getObject();
117
118 /**
119 * gets the path, which is a string representation of specifically which attribute (at some depth) is being
120 * accessed
121 *
122 * <p>For example, on a person object there might be the following field path:
123 * joe.home.mailingAddress.state</p>
124 *
125 * @return the string representation of the attribute identifier currently being processed
126 */
127 public String getPath();
128
129 /**
130 * gets the type of the attribute specified - A Java class
131 *
132 * @param attributeName - the name of attribute
133 * @return the type of the attribute referenced by the passed name, or null if no attribute exists of that name
134 */
135 public Class<?> getType(String attributeName);
136
137 /**
138 * Indicates whether the configured attribute name is readable for the object
139 *
140 * @return boolean if attribute is readable, false if not
141 */
142 public boolean isReadable();
143
144 /**
145 * looks up the attribute value that is currently being processed
146 *
147 * @param <X> - the type of the attribute
148 * @return the attribute's value if found, null if not
149 * @throws AttributeValidationException
150 */
151 public <X> X getValue() throws AttributeValidationException;
152
153 /**
154 * looks up any attribute value by name for the object being processed
155 *
156 * @param <X> - the type of the attribute
157 * @param attributeName - the name of attribute whose value is looked up
158 * @return - the attribute's value if found, null if not
159 * @throws AttributeValidationException
160 */
161 public <X> X getValue(String attributeName) throws AttributeValidationException;
162
163 /**
164 * enables legacy processing of string representations of attribute values like a date range in the format
165 * 12/03/2001..1/29/2009
166 *
167 * @param attributeName - the attribute name
168 * @return the list of token strings for the attribute value of the named attribute
169 * @throws AttributeValidationException
170 */
171 public List<String> getCleanSearchableValues(String attributeName) throws AttributeValidationException;
172
173 /**
174 * Setter for the current attribute that is being processed
175 *
176 * @param attributeName
177 */
178 public void setAttributeName(String attributeName);
179
180 /**
181 * overrides {@link Object#clone()}
182 *
183 * @return a cloned {@code AttributeValueReader}
184 */
185 public AttributeValueReader clone();
186
187 }
188