001/**
002 * Copyright 2005-2018 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.inquiry;
017
018import org.kuali.rice.krad.uif.widget.Inquiry;
019
020import 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 */
028public interface Inquirable {
029
030    /**
031     * 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     * @return inquiry data object class
039     */
040    Class<?> getDataObjectClass();
041
042    /**
043     * @see Inquirable#getDataObjectClass()
044     */
045    void setDataObjectClass(Class<?> dataObjectClass);
046
047    /**
048     * Responsible for retrieving the data object from its data source
049     * (database, service call, etc) based on the given map of field
050     * name/value pairs
051     *
052     * <p>
053     * Given map can contain more than fields (primary key or other) necessary
054     * for retrieving the data object. Method will use the fields necessary
055     * based on the metadata for the data object class configured on the inquirable
056     * </p>
057     *
058     * @param fieldValues - a map of string field names and values
059     * @return the data object or null if not found
060     */
061    Object retrieveDataObject(Map<String, String> fieldValues);
062
063    /**
064     * Invoked by the <code>ViewHelperService</code> to build a link to the
065     * inquiry
066     *
067     * <p>
068     * Note this is used primarily for custom <code>Inquirable</code>
069     * implementations to customize the inquiry class or parameters for an
070     * inquiry. Instead of building the full inquiry link, implementations can
071     * make a callback to
072     * org.kuali.rice.krad.uif.widget.Inquiry.buildInquiryLink(Object, String,
073     * Class<?>, Map<String, String>) given an inquiry class and parameters to
074     * build the link field.
075     * </p>
076     *
077     * @param dataObject - parent object for the inquiry property
078     * @param propertyName - name of the property the inquiry is being built for
079     * @param inquiry - instance of the inquiry widget being built for the property
080     */
081    void buildInquirableLink(Object dataObject, String propertyName, Inquiry inquiry);
082}