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 org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
019import org.kuali.rice.krad.uif.view.View;
020import org.kuali.rice.krad.uif.component.Component;
021import org.kuali.rice.krad.uif.component.Ordered;
022
023import java.io.Serializable;
024import java.util.List;
025import java.util.Set;
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 view - View instance the component modifier is a part of
069     * @parma model - object instance containing the view data
070     * @param component - Component the modifier is configured on
071     * @see org.kuali.rice.krad.uif.service.ViewHelperService#performInitialization
072     */
073    public void performInitialization(View view, Object model, Component component);
074
075    /**
076     * Invoked within the configured phase of the component lifecycle. This is
077     * where the <code>ComponentModifier</code> should perform its work against
078     * the given <code>Component</code> instance
079     *
080     * @param view - the view instance to which the component belongs
081     * @param model - top level object containing the view data
082     * @param component - the component instance to modify
083     * @see org.kuali.rice.krad.uif.modifier.ComponentModifier#performModification
084     *      (View, Object, Component)
085     */
086    public void performModification(View view, Object model, Component component);
087
088    /**
089     * <code>Set</code> of <code>Component</code> classes that may be sent to
090     * the modifier
091     *
092     * <p>
093     * If an empty or null list is returned, it is assumed the modifier supports
094     * all components. The returned set will be used by the dictionary
095     * validation
096     * </p>
097     *
098     * @return Set component classes
099     */
100    public Set<Class<? extends Component>> getSupportedComponents();
101
102    /**
103     * List of components that are maintained by the modifier as prototypes for creating other component instances
104     *
105     * <p>
106     * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
107     * are the fields in a collection group that are created for each collection record. They only participate in the
108     * initialize phase.
109     * </p>
110     *
111     * @return List<Component> child component prototypes
112     */
113    public List<Component> getComponentPrototypes();
114
115    /**
116     * Indicates what phase of the component lifecycle the
117     * <code>ComponentModifier</code> should be invoked in (INITIALIZE,
118     * APPLY_MODEL, or FINALIZE)
119     *
120     * @return String view lifecycle phase
121     * @see org.kuali.rice.krad.uif.UifConstants.ViewPhases
122     */
123    public String getRunPhase();
124
125    /**
126     * Conditional expression to evaluate for determining whether the component
127     * modifier should be run. If the expression evaluates to true the modifier
128     * will be executed, otherwise it will not be executed
129     *
130     * @return String el expression that should evaluate to boolean
131     */
132    public String getRunCondition();
133
134    /**
135     * @see org.springframework.core.Ordered#getOrder()
136     */
137    public int getOrder();
138
139    /**
140     * @see org.kuali.rice.krad.uif.component.Ordered#setOrder(int)
141     */
142    public void setOrder(int order);
143
144    /**
145     * Copy the object
146     *
147     * @return the copied object
148     */
149    public <T> T copy();
150}