001    /**
002     * Copyright 2005-2013 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     */
016    package org.kuali.rice.krad.inquiry;
017    
018    import org.kuali.rice.krad.uif.widget.Inquiry;
019    
020    import java.util.Map;
021    
022    /**
023     * Provides the contract for implementing an inquiry within the
024     * inquiry framework
025     *
026     * @author Kuali Rice Team (rice.collab@kuali.org)
027     */
028    public interface Inquirable {
029    
030        /**
031         * Sets the class for the data object the inquirable should retrieve
032         *
033         * <p>
034         * Must be set before invoking any other operations on the <code>Inquirable</code>,
035         * including the retrieveDataObject method
036         * </p>
037         *
038         * @param dataObjectClass the class of the dataObject that this inquirable should
039         * retrieve
040         */
041        public void setDataObjectClass(Class<?> dataObjectClass);
042    
043        /**
044         * Responsible for retrieving the data object from its data source
045         * (database, service call, etc) based on the given map of field
046         * name/value pairs
047         *
048         * <p>
049         * Given map can contain more than fields (primary key or other) necessary
050         * for retrieving the data object. Method will use the fields necessary
051         * based on the metadata for the data object class configured on the inquirable
052         * </p>
053         *
054         * @param fieldValues - a map of string field names and values
055         * @return the data object or null if not found
056         */
057        public Object retrieveDataObject(Map<String, String> fieldValues);
058    
059        /**
060         * Invoked by the <code>ViewHelperService</code> to build a link to the
061         * inquiry
062         *
063         * <p>
064         * Note this is used primarily for custom <code>Inquirable</code>
065         * implementations to customize the inquiry class or parameters for an
066         * inquiry. Instead of building the full inquiry link, implementations can
067         * make a callback to
068         * org.kuali.rice.krad.uif.widget.Inquiry.buildInquiryLink(Object, String,
069         * Class<?>, Map<String, String>) given an inquiry class and parameters to
070         * build the link field.
071         * </p>
072         *
073         * @param dataObject - parent object for the inquiry property
074         * @param propertyName - name of the property the inquiry is being built for
075         * @param inquiry - instance of the inquiry widget being built for the property
076         */
077        public void buildInquirableLink(Object dataObject, String propertyName, Inquiry inquiry);
078    }