001/**
002 * Copyright 2005-2016 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 * An interface to define classes that encapsulate access to both dictionary metadata and object field values, for example, by reflection
025 * and introspection, for the purpose of performing validation against constraints defined in the DictionaryValidationService implementation. 
026 * 
027 * Practically speaking, this interface should only need to be implemented by a small number of classes. The two major use cases are for 
028 * (1) a dictionary object with members 
029 * (2) a specific member of a dictionary object
030 * 
031 * In the first case, implementing classes should provide access to all underlying members of the object via reflection or some other mechanism. 
032 * In the second case, implementing classes only need to provide access to the value associated with that specific member, and constraints
033 * requiring access to additional members will be skipped. 
034 * 
035 * @author Kuali Rice Team (rice.collab@kuali.org)
036 * @since 1.1
037 */
038public interface AttributeValueReader {
039
040        /**
041         * This method is an accessor for the attribute name that is currently being processed by the DictionaryValidationService implementation. 
042         * 
043         * @return the current attribute name being processed
044         */
045        public String getAttributeName();
046        
047        /**
048         * This method provides access to the constrainable attribute definition of a specific attribute name. If the value of the metadata 
049         * associated with the object field does not implement constrainable, or if no metadata is associated with this object field, 
050         * then null should be returned. 
051         * 
052         * @param attributeName - the name of the attribute/field whose metadata is being requested
053         * @return dictionary metadata object implementing some constrainable capability 
054         */
055        public Constrainable getDefinition(String attributeName);
056        
057        /**
058         * This method returns a list of all constrainable dictionary metadata definitions for attributes or fields encapsulated by this object.
059         * 
060         * @return a list of constrainable definitions
061         */
062        public List<Constrainable> getDefinitions();
063        
064        /**
065         * The dictionary metadata associated with an object (its "entry" in the dictionary) can also be constrainable, in which case the object
066         * value itself can be validated against one or more constraints. If the specific entry for the dictionary object encapsulated by this 
067         * reader is not constrainable, or if no entry exists for this dictionary object, or no dictionary object is being encapsulted, then
068         * null should be returned. 
069         * 
070         * @return the constrainable dictionary entry metadata for this object, or null
071         */
072        public Constrainable getEntry();
073        
074        /**
075         * An entry name should be returned for the purposes of correcting looking up errors, which are generally found by entry name +
076         * attribute name + error key.
077         * 
078         * @return the name that the data dictionary uses to store metadata about this object (not its attributes)
079         */
080        public String getEntryName();
081        
082        /**
083         * This method looks up a label for a specific attribute name. 
084         * 
085         * @param attributeName
086         * @return some descriptive label that can be exposed to the end user for error messages
087         */
088        public String getLabel(String attributeName);
089        
090        /**
091         * The underlying object itself (not the field/attribute value, but the object).  
092         * 
093         * @return the object that is being encapsulated by this reader, or null if no object is being encapsulated. 
094         */
095        public Object getObject();
096        
097        /**
098         * The path is a string representation of specifically which attribute (at some depth) is being accessed, for example, on a 
099         * person object there might be the following field path:
100         * 
101         * joe.home.mailingAddress.state
102         * 
103         * @return the string representation of the attribute identifier currently being processed
104         */
105        public String getPath();
106        
107        /**
108         * The type of the attribute specified. A Java class. 
109         * 
110         * @param attributeName
111         * @return the type of the attribute referenced by the passed name, or null if no attribute exists of that name
112         */
113        public Class<?> getType(String attributeName);
114
115    /**
116     * Indicates whether the configured attribute name is readable for the object
117     *
118     * @return boolean if attribute is readable, false if not
119     */
120    public boolean isReadable();
121        
122        /**
123         * A convenience method for looking up the attribute value that is currently being processed. 
124         * 
125         * @param <X>
126         * @return
127         * @throws AttributeValidationException
128         */
129        public <X> X getValue() throws AttributeValidationException;
130        
131        /**
132         * A method for looking up any attribute value by name for the object being processed. 
133         * 
134         * @param <X>
135         * @param attributeName
136         * @return
137         * @throws AttributeValidationException
138         */
139        public <X> X getValue(String attributeName) throws AttributeValidationException;
140        
141        /**
142         * A method to enable legacy processing of string representations of attribute values like a date range in the format 
143         * 12/03/2001..1/29/2009 
144         * 
145         * @param attributeName
146         * @return the list of token strings for the attribute value of the named attribute
147         * @throws AttributeValidationException
148         */
149        public List<String> getCleanSearchableValues(String attributeName) throws AttributeValidationException;
150        
151        /**
152         * Setter for the current attribute that is being processed.
153         * 
154         * @param attributeName
155         */
156        public void setAttributeName(String attributeName);
157    
158    public AttributeValueReader clone();
159        
160}
161