1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
/*******************************************************************************
* Copyright (c) 2011, 2013 Wind River Systems, Inc. and others. All rights reserved.
* This program and the accompanying materials are made available under the terms
* of the Eclipse Public License v1.0 which accompanies this distribution, and is
* available at http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Wind River Systems - initial API and implementation
*******************************************************************************/
package org.eclipse.tcf.te.runtime.stepper.interfaces;
import java.util.Map;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;
import org.eclipse.tcf.te.runtime.interfaces.callback.ICallback;
import org.eclipse.tcf.te.runtime.interfaces.extensions.IExecutableExtension;
import org.eclipse.tcf.te.runtime.interfaces.properties.IPropertiesContainer;
/**
* A single step.
* <p>
* Steps are assumed to be asynchronous. If the step execution finished, the passed in <b>callback
* must be invoked</b>. The parent stepper suspend the step sequence execution till the callback is
* invoked.
* <p>
* Steps signals the execution state to the parent stepper via the <code>IStatus</code> object
* passed to the callback as first argument. The status object is mandatory and cannot be
* <code>null</code>. If the step execution succeeds, an status with severity {@link IStatus#OK} is
* expected.
*/
public interface IStep extends IExecutableExtension {
/**
* Additional data property for ICallback.
*/
public static final String CALLBACK_PROPERTY_DATA = "data"; //$NON-NLS-1$
/**
* Executes the context step logic.
*
* @param context The context. Must not be <code>null</code>.
* @param data The data giving object. Must not be <code>null</code>.
* @param fullQualifiedId The full qualified id for this step. Must not be <code>null</code>.
* @param monitor The progress monitor. Must not be <code>null</code>.
* @param callback The callback to invoke if finished. Must not be <code>null</code>.
*/
public void execute(IStepContext context, IPropertiesContainer data, IFullQualifiedId fullQualifiedId, IProgressMonitor monitor, ICallback callback);
/**
* Returns if or if not this step can have multiple references within step groups. If
* <code>true</code> is returned, the step can occur exactly once per step group. This method
* effects all defined step groups and overwrite individual step settings.
* <p>
* The default implementation returns <code>false</code>.
*
* @return <code>True</code> if the step can be referenced only ones per step group,
* <code>false</code> otherwise.
*/
public boolean isSingleton();
/**
* Initialize the step from the given data.
*
* @param context The context. Must not be <code>null</code>.
* @param data The data. Must not be <code>null</code>.
* @param fullQualifiedId The full qualified id for this step. Must not be <code>null</code>.
* @param monitor The progress monitor. Must not be <code>null</code>.
*/
public void initializeFrom(IStepContext context, IPropertiesContainer data, IFullQualifiedId fullQualifiedId, IProgressMonitor monitor);
/**
* Validate execution conditions.
* <p>
* This method is called from
* {@link #execute(IAdaptable, IPropertiesContainer, IFullQualifiedId, IProgressMonitor, ICallback)}
* after the step initialization. If any execution condition is not fulfilled, the method should
* throw an {@link CoreException} to signal the failure.
*
* @param context The context. Must not be <code>null</code>.
* @param data The data. Must not be <code>null</code>.
* @param fullQualifiedId The full qualified id for this step. Must not be <code>null</code>.
* @param monitor The progress monitor. Must not be <code>null</code>.
*
* @throws CoreException if the execution cannot be continue. The associated status should
* describe the failure cause.
*/
public void validateExecute(IStepContext context, IPropertiesContainer data, IFullQualifiedId fullQualifiedId, IProgressMonitor monitor) throws CoreException;
/**
* Cleanup intermediate data of the step.
* <p>
* This method will be called at the end of each step execution.
*
* @param context The context. Must not be <code>null</code>.
* @param data The data. Must not be <code>null</code>.
* @param fullQualifiedId The full qualified id for this step. Must not be <code>null</code>.
* @param monitor The progress monitor. Must not be <code>null</code>.
*/
public void cleanup(IStepContext context, IPropertiesContainer data, IFullQualifiedId fullQualifiedId, IProgressMonitor monitor);
/**
* Called from the stepper engine once an error occurred during the stepping. Gives each step,
* completed previously to the error, the possibility to rollback whatever the step did.
* <p>
* <b>Note:</b> It is not guaranteed that the shared step data hasn't been overwritten in the
* meanwhile by multiple invocation of the same step. If a step supports multiple invocations,
* the implementer of the step is required to identify all the step data to rollback by himself.
* <p>
* IProgressMonitor.worked(int) should not be used for the given progress monitor. Setting sub task labels is ok.
*
* @param context The context. Must not be <code>null</code>.
* @param data The data. Must not be <code>null</code>.
* @param status The status of the last step executed and that caused the rollback.
* @param fullQualifiedId The full qualified id for this step. Must not be <code>null</code>.
* @param monitor The progress monitor. Must not be <code>null</code>.
* @param callback The callback to invoke if finished. Must not be <code>null</code>.
*/
public void rollback(IStepContext context, IPropertiesContainer data, IStatus status, IFullQualifiedId fullQualifiedId, IProgressMonitor monitor, ICallback callback);
/**
* Get the timeout in milliseconds to wait for finish
* when the progress monitor was canceled.
* If a step should not have a timeout and handles the cancel itself return -1.
* @return Timeout in milliseconds.
*/
public int getCancelTimeout();
/**
* Returns the number of total work the step is consuming.
*
* @return The number of total work or {@link IProgressMonitor#UNKNOWN}.
*/
public int getTotalWork(IStepContext context, IPropertiesContainer data);
/**
* Returns the list of required context step or context step group id's. The execution of a
* context step fails if not all of the required steps are available or have not been executed
* before.
* <p>
* If the listed required steps have dependencies on their own, these dependencies are
* implicitly inherited.
*
* @return The list of required context step or context step group id's or an empty list.
*/
public String[] getDependencies();
/**
* Set additional parameters for this step
* @param parameters
*/
public void setParameters(Map<String,String> parameters);
/**
* Returns a map of additional parameters given through the parameters section in the Reference section of a StepGroups.
* @return The parameters of an empty Map.
*/
public Map<String,String> getParameters();
}
|
