001/**
002 * Copyright 2005-2014 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.krad.datadictionary.validation;
017
018import org.kuali.rice.krad.datadictionary.exception.AttributeValidationException;
019import org.kuali.rice.krad.datadictionary.validation.capability.Constrainable;
020
021import java.util.List;
022
023/**
024 * AttributeValueReader defines classes that encapsulate access to both dictionary metadata and object field values
025 *
026 * <p>For example, by reflection
027 * and introspection, for the purpose of performing validation against constraints defined in the
028 * DictionaryValidationService implementation.</p>
029 *
030 * <p>Practically speaking, this interface should only need to be implemented by a small number of classes. The two
031 * major use cases are for
032 * <ol>
033 * <li> a dictionary object with members</li>
034 * <li> a specific member of a dictionary object</li>
035 * </ol>
036 * </p>
037 * <p>
038 * In the first case, implementing classes should provide access to all underlying members of the object via reflection
039 * or some other mechanism.
040 * In the second case, implementing classes only need to provide access to the value associated with that specific
041 * member, and constraints
042 * requiring access to additional members will be skipped.</p>
043 *
044 * @author Kuali Rice Team (rice.collab@kuali.org)
045 * @since 1.1
046 */
047public interface AttributeValueReader {
048
049    /**
050     * acts as an accessor for the attribute name that is currently being processed by the DictionaryValidationService
051     * implementation
052     *
053     * @return the current attribute name being processed
054     */
055    public String getAttributeName();
056
057    /**
058     * provides access to the constrainable attribute definition of a specific attribute name
059     *
060     * <p>If the value of the metadata
061     * associated with the object field does not implement constrainable, or if no metadata is associated with this
062     * object
063     * field,
064     * then null should be returned.</p>
065     *
066     * @param attributeName - the name of the attribute/field whose metadata is being requested
067     * @return dictionary metadata object implementing some constrainable capability
068     */
069    public Constrainable getDefinition(String attributeName);
070
071    /**
072     * gets a list of all constrainable dictionary metadata definitions for attributes or fields encapsulated by this
073     * object
074     *
075     * @return a list of constrainable definitions
076     */
077    public List<Constrainable> getDefinitions();
078
079    /**
080     * gets the dictionary metadata associated with an object (its "entry" in the dictionary)
081     *
082     * <p>It can also be constrainable, in which case the object
083     * value itself can be validated against one or more constraints. If the specific entry for the dictionary object
084     * encapsulated by this
085     * reader is not constrainable, or if no entry exists for this dictionary object, or no dictionary object is being
086     * encapsulted, then
087     * null should be returned.
088     * </p>
089     *
090     * @return the constrainable dictionary entry metadata for this object, or null
091     */
092    public Constrainable getEntry();
093
094    /**
095     * gets the entry name for the purposes of correct error look up
096     *
097     * <p>Errors are generally found by entry name + attribute name + error key</p>
098     *
099     * @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