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.uif.lifecycle;
017
018import java.util.List;
019
020import org.kuali.rice.krad.uif.component.Component;
021import org.kuali.rice.krad.uif.lifecycle.ViewLifecycle.LifecycleEvent;
022import org.kuali.rice.krad.uif.util.LifecycleElement;
023
024/**
025 * Represents a phase in the view lifecycle.
026 *
027 * <p>A phase is contains a collection of {@link org.kuali.rice.krad.uif.lifecycle.ViewLifecycleTask} instances
028 * that are processed on each component in the view tree.</p>
029 *
030 * @author Kuali Rice Team (rice.collab@kuali.org)
031 */
032public interface ViewLifecyclePhase extends LifecycleElementState, Runnable {
033
034    /**
035     * Prepares a phase for use after being recycled (state cleared).
036     *
037     * @param element lifecycle element to prepare
038     * @param parentPath path of the element related to its parent (in other words the property of the parent
039     * that holds this element)
040     * @param parent parent component
041     * @param refreshPaths during a component refresh request, the list of view paths that should be processed
042     * by the phase (this includes a subset of the entire view tree)
043     */
044    void prepare(LifecycleElement element, Component parent, String parentPath, List<String> refreshPaths);
045
046    /**
047     * Retrieves the component that is a parent to the element being processed in the
048     * view three.
049     *
050     * @return parent component
051     */
052    Component getParent();
053
054    /**
055     * Determines if this lifecycle phase has completed processing.
056     *
057     * <p>
058     * This method will return true when this phase's tasks have been processed, but does not
059     * necessarily indicate that successor phases have been completed. Use {@link #isComplete()} to
060     * determine if the lifecycle has been fully completed for this phase.
061     * </p>
062     *
063     * @return true if this phase has been processed, false if not
064     */
065    boolean isProcessed();
066
067    /**
068     * Determines if this lifecycle phase and all successor phases, have completed processing.
069     *
070     * @return true if this phase and all successor phases have been processed, false if not
071     * @see Component#notifyCompleted(ViewLifecyclePhase)
072     */
073    boolean isComplete();
074
075    /**
076     * Gets the task currently running.
077     *
078     * @return the task currently running, null if this phase is not active.
079     */
080    ViewLifecycleTask<?> getCurrentTask();
081
082    /**
083     * Gets the event to notify on completion.
084     *
085     * @return lifecycle event to notify on completion
086     * @see ViewLifecycle.LifecycleEvent
087     */
088    LifecycleEvent getEventToNotify();
089
090    /**
091     * Gets the expected view status prior to phase execution.
092     *
093     * @return expected view status prior to phase execution
094     */
095    String getStartViewStatus();
096
097    /**
098     * Gets the expected view status after phase execution.
099     *
100     * @return expected view status after phase execution
101     */
102    String getEndViewStatus();
103
104    /**
105     * Gets the lifecycle phase that directly precedes this phase.
106     *
107     * @return lifecycle phase that directly precedes this phase
108     */
109    ViewLifecyclePhase getPredecessor();
110
111    /**
112     * Sets the next phase, to queue for processing after this phase is completed.
113     *
114     * @param nextPhase next phase
115     * @throws IllegalArgumentException If nextPhase is null, or if the view status of the phases don't match.
116     * @throws IllegalStateException If the nextPhase has been set to a non-null value already.
117     */
118    void setNextPhase(ViewLifecyclePhase nextPhase);
119
120    /**
121     * Sets the predecessor, for notification during processing.
122     *
123     * @param phase predecessor phase
124     */
125    void setPredecessor(ViewLifecyclePhase phase);
126
127    /**
128     * Sets the refresh paths for this phase.
129     *
130     * @param refreshPaths list of refresh paths.
131     */
132    void setRefreshPaths(List<String> refreshPaths);
133
134    /**
135     * During a component refresh, returns the list of view paths the lifecycle phase will be processed on.
136     *
137     * @return list of view paths
138     */
139    List<String> getRefreshPaths();
140
141    /**
142     * Determines of there are any pending successors of this phase.
143     *
144     * @return True if there are pending successors, false if no successors are pending.
145     */
146    boolean hasPendingSuccessors();
147
148    /**
149     * Remove a pending successor by path.
150     *
151     * @param parentPath path
152     */
153    void removePendingSuccessor(String parentPath);
154
155    /**
156     * Invoked by the processor when this phase and all successors have completely processed.
157     */
158    void notifyCompleted();
159
160    /**
161     * Prepares this phase instance for recycled use.
162     */
163    void recycle();
164
165}