001/**
002 * Copyright 2005-2015 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.uif.modifier;
017
018import java.io.Serializable;
019import java.util.List;
020import java.util.Set;
021
022import org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
023import org.kuali.rice.krad.uif.component.Component;
024import org.kuali.rice.krad.uif.component.Ordered;
025import org.kuali.rice.krad.uif.lifecycle.RunComponentModifiersTask;
026
027/**
028 * Provides modification functionality for a <code>Component</code>
029 *
030 * <p>
031 * <code>ComponentModifier</code> instances are configured by the component's
032 * dictionary definition. They can be used to provide dynamic initialization
033 * behavior for a certain type of component or all components based on the
034 * getComponentsForLifecycle method. In addition they can do dynamic generation of
035 * new <code>Component</code> instances, or replacement of the components or
036 * their properties.
037 * </p>
038 *
039 * <p>
040 * Modifiers provide for more usability and flexibility of component
041 * configuration. For instance if a <code>Group</code> definition is already
042 * configured that is close to what the developer needs, but they need to make
043 * global changes of the group, then can invoke or create a
044 * <code>ComponentModifier</code> for the group to apply those changes. The
045 * configuration can then inherit the exiting group definition and then specify
046 * the modifier to run with the component's componentModifiers property.
047 * </p>
048 *
049 * @author Kuali Rice Team (rice.collab@kuali.org)
050 */
051public interface ComponentModifier extends UifDictionaryBean, Serializable, Ordered {
052
053    /**
054     * Should be called to initialize the ComponentModifier
055     *
056     * <p>
057     * This is where component modifiers can set defaults and setup other necessary
058     * state. The initialize method should only be called once per layout
059     * manager lifecycle and is invoked within the initialize phase of the view
060     * lifecylce.
061     * </p>
062     *
063     * <p>
064     * Note if the component modifier holds nested components, they should be initialized
065     * in this method by calling the view helper service
066     * </p>
067     *
068     * @param model - object instance containing the view data
069     * @param component - Component the modifier is configured on
070     * @see RunComponentModifiersTask
071     */
072    public void performInitialization(Object model, Component component);
073
074    /**
075     * Invoked within the configured phase of the component lifecycle. This is
076     * where the <code>ComponentModifier</code> should perform its work against
077     * the given <code>Component</code> instance
078     *
079     * @param model - top level object containing the view data
080     * @param component - the component instance to modify
081     * @see RunComponentModifiersTask
082     */
083    public void performModification(Object model, Component component);
084
085    /**
086     * <code>Set</code> of <code>Component</code> classes that may be sent to
087     * the modifier
088     *
089     * <p>
090     * If an empty or null list is returned, it is assumed the modifier supports
091     * all components. The returned set will be used by the dictionary
092     * validation
093     * </p>
094     *
095     * @return Set component classes
096     */
097    public Set<Class<? extends Component>> getSupportedComponents();
098
099    /**
100     * List of components that are maintained by the modifier as prototypes for creating other component instances
101     *
102     * <p>
103     * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
104     * are the fields in a collection group that are created for each collection record. They only participate in the
105     * initialize phase.
106     * </p>
107     *
108     * @return List<Component> child component prototypes
109     */
110    public List<Component> getComponentPrototypes();
111
112    /**
113     * Indicates what phase of the component lifecycle the
114     * <code>ComponentModifier</code> should be invoked in (INITIALIZE,
115     * APPLY_MODEL, or FINALIZE)
116     *
117     * @return String view lifecycle phase
118     * @see org.kuali.rice.krad.uif.UifConstants.ViewPhases
119     */
120    public String getRunPhase();
121
122    /**
123     * Conditional expression to evaluate for determining whether the component
124     * modifier should be run. If the expression evaluates to true the modifier
125     * will be executed, otherwise it will not be executed
126     *
127     * @return String el expression that should evaluate to boolean
128     */
129    public String getRunCondition();
130
131    /**
132     * @see org.springframework.core.Ordered#getOrder()
133     */
134    public int getOrder();
135
136    /**
137     * @see org.kuali.rice.krad.uif.component.Ordered#setOrder(int)
138     */
139    public void setOrder(int order);
140
141}