1 /**
2 * Copyright 2005-2014 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.uif.modifier;
17
18 import org.kuali.rice.krad.datadictionary.uif.UifDictionaryBean;
19 import org.kuali.rice.krad.uif.component.Component;
20 import org.kuali.rice.krad.uif.component.Ordered;
21 import org.kuali.rice.krad.uif.lifecycle.RunComponentModifiersTask;
22 import org.kuali.rice.krad.uif.util.UifCloneable;
23
24 import java.io.Serializable;
25 import java.util.List;
26 import java.util.Set;
27
28 /**
29 * Provides modification functionality for a <code>Component</code>
30 *
31 * <p>
32 * <code>ComponentModifier</code> instances are configured by the component's
33 * dictionary definition. They can be used to provide dynamic initialization
34 * behavior for a certain type of component or all components based on the
35 * getComponentsForLifecycle method. In addition they can do dynamic generation of
36 * new <code>Component</code> instances, or replacement of the components or
37 * their properties.
38 * </p>
39 *
40 * <p>
41 * Modifiers provide for more usability and flexibility of component
42 * configuration. For instance if a <code>Group</code> definition is already
43 * configured that is close to what the developer needs, but they need to make
44 * global changes of the group, then can invoke or create a
45 * <code>ComponentModifier</code> for the group to apply those changes. The
46 * configuration can then inherit the exiting group definition and then specify
47 * the modifier to run with the component's componentModifiers property.
48 * </p>
49 *
50 * @author Kuali Rice Team (rice.collab@kuali.org)
51 */
52 public interface ComponentModifier extends UifDictionaryBean, Serializable, Ordered, UifCloneable {
53
54 /**
55 * Should be called to initialize the ComponentModifier
56 *
57 * <p>
58 * This is where component modifiers can set defaults and setup other necessary
59 * state. The initialize method should only be called once per layout
60 * manager lifecycle and is invoked within the initialize phase of the view
61 * lifecylce.
62 * </p>
63 *
64 * <p>
65 * Note if the component modifier holds nested components, they should be initialized
66 * in this method by calling the view helper service
67 * </p>
68 *
69 * @param model - object instance containing the view data
70 * @param component - Component the modifier is configured on
71 * @see RunComponentModifiersTask
72 */
73 public void performInitialization(Object model, Component component);
74
75 /**
76 * Invoked within the configured phase of the component lifecycle. This is
77 * where the <code>ComponentModifier</code> should perform its work against
78 * the given <code>Component</code> instance
79 *
80 * @param model - top level object containing the view data
81 * @param component - the component instance to modify
82 * @see RunComponentModifiersTask
83 */
84 public void performModification(Object model, Component component);
85
86 /**
87 * <code>Set</code> of <code>Component</code> classes that may be sent to
88 * the modifier
89 *
90 * <p>
91 * If an empty or null list is returned, it is assumed the modifier supports
92 * all components. The returned set will be used by the dictionary
93 * validation
94 * </p>
95 *
96 * @return Set component classes
97 */
98 public Set<Class<? extends Component>> getSupportedComponents();
99
100 /**
101 * List of components that are maintained by the modifier as prototypes for creating other component instances
102 *
103 * <p>
104 * Prototypes are held for configuring how a component should be created during the lifecycle. An example of this
105 * are the fields in a collection group that are created for each collection record. They only participate in the
106 * initialize phase.
107 * </p>
108 *
109 * @return List<Component> child component prototypes
110 */
111 public List<Component> getComponentPrototypes();
112
113 /**
114 * Indicates what phase of the component lifecycle the
115 * <code>ComponentModifier</code> should be invoked in (INITIALIZE,
116 * APPLY_MODEL, or FINALIZE)
117 *
118 * @return String view lifecycle phase
119 * @see org.kuali.rice.krad.uif.UifConstants.ViewPhases
120 */
121 public String getRunPhase();
122
123 /**
124 * Conditional expression to evaluate for determining whether the component
125 * modifier should be run. If the expression evaluates to true the modifier
126 * will be executed, otherwise it will not be executed
127 *
128 * @return String el expression that should evaluate to boolean
129 */
130 public String getRunCondition();
131
132 /**
133 * @see org.springframework.core.Ordered#getOrder()
134 */
135 public int getOrder();
136
137 /**
138 * @see org.kuali.rice.krad.uif.component.Ordered#setOrder(int)
139 */
140 public void setOrder(int order);
141
142 /**
143 * Copy the object
144 * @param <T> The type being copied
145 *
146 * @return the copied object
147 */
148 public <T> T copy();
149
150 }