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.datadictionary.state;
017
018import org.kuali.rice.krad.datadictionary.validator.ValidationTrace;
019
020import java.util.List;
021import java.util.Map;
022
023/**
024 * StateMapping defines the methods necessary to allow for state validation to apply to a state object
025 *
026 * @author Kuali Rice Team (rice.collab@kuali.org)
027 * @since 2.2
028 */
029public interface StateMapping {
030
031    /**
032     * Gets the currentState by looking at the statePropertyName on the stateObject passed in
033     *
034     * @param stateObject the object containing the state information
035     * @return the currentState of the object
036     */
037    public String getCurrentState(Object stateObject);
038
039    /**
040     * Gets the nextState of the object passed in by looking at the statePropertyName and using the states list
041     * to determine the next state in order.  Returns the currentState if there is no next state.
042     *
043     * @param stateObject the object containing the state information
044     * @return the next state of the object, or current state if no next state exists
045     */
046    public String getNextState(Object stateObject);
047
048    /**
049     * Returns the human readable message determined by the key set for the state passed in
050     * against the stateNameMessageKeyMap.  If the state cannot be found in the states list or the state passed in is
051     * blank, this method will return null.  If the key found does not match a message, this method will return the
052     * state
053     * passed in.
054     *
055     * @param state state to get the message for
056     * @return state message, or the state passed in (if a valid state in states). Otherwise, returns null.
057     */
058    public String getStateNameMessage(String state);
059
060    /**
061     * Map used by getStateNameMessage to determine the key to use when retrieving the message for the state specified.
062     * The map should be defined as state:messageKeyForState.
063     *
064     * @return map of states and their messageKeys
065     */
066    public Map<String, String> getStateNameMessageKeyMap();
067
068    /**
069     * Set the stateNameMessageKeyMap
070     *
071     * @param stateNameMessageKeyMap map of states and their messageKeys
072     */
073    public void setStateNameMessageKeyMap(Map<String, String> stateNameMessageKeyMap);
074
075    /**
076     * The states of this stateMapping.  IMPORTANT: This must be ALL states for this mapping IN ORDER.
077     *
078     * @return list of states, in the order in which they are applied.  If states were never set, returns an empty
079     *         list.
080     */
081    public List<String> getStates();
082
083    /**
084     * Set the states of this stateMapping, in order
085     *
086     * @param states list of states, in the order in which they are applied.
087     */
088    public void setStates(List<String> states);
089
090    /**
091     * The property name/path to be used when trying to find state String information on the object.  This is used by
092     * getCurrentState(Object object)
093     * and getNextState(Object object);
094     *
095     * @return the property name/path representing where state information can be found on the object
096     */
097    public String getStatePropertyName();
098
099    /**
100     * Set the property name/path
101     *
102     * @param name the property name/path that points to the string representation of the object's tate
103     */
104    public void setStatePropertyName(String name);
105
106    /**
107     * This ONLY applies to client side validations as the controller has full control over what validations to apply
108     * on the server.  This setting determines for what states, if any, the client side validation needs to use for
109     * its validation instead of the default (by default if state validation is setup, the client side validation
110     * will use n+1 as its validation, ie whatever the NEXT state is).
111     *
112     * <p>The map must be defined as such: (state of the object, state to use for validation on the
113     * client when in that state).<br>
114     * Example:<br>
115     * key="INITIAL" value="SUBMIT"<br>
116     * key="SAVE" value="SUBMIT"<br>
117     * In this example, when the object is in the "INITIAL" or the "SAVE" states, validation on the client will
118     * be against the "SUBMIT" state</p>
119     *
120     * @return map representing the state of the object and state to use for validation on the
121     *         client when in that state
122     */
123    public Map<String, String> getCustomClientSideValidationStates();
124
125    /**
126     * Set the custom client side validation behavior map.  This only applies for client-side validation.
127     *
128     * @param customClientSideValidationStates map representing the state of the object and state to use for validation
129     * on the
130     * client when in that state
131     */
132    public void setCustomClientSideValidationStates(Map<String, String> customClientSideValidationStates);
133
134    /**
135     * Validates different requirements of component compiling a series of reports detailing information on errors
136     * found in the component.  Used by the RiceDictionaryValidator.
137     *
138     * @param tracer Record of component's location
139     */
140    public void completeValidation(ValidationTrace tracer);
141
142}