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