1 /*******************************************************************************
2 * Copyright (c) 2012 Ericsson
4 * All rights reserved. This program and the accompanying materials are
5 * made available under the terms of the Eclipse Public License v1.0 which
6 * accompanies this distribution, and is available at
7 * http://www.eclipse.org/legal/epl-v10.html
10 * Francois Chouinard - Initial API and implementation
11 *******************************************************************************/
13 package org
.eclipse
.linuxtools
.tmf
.core
.request
;
15 import org
.eclipse
.core
.runtime
.IStatus
;
16 import org
.eclipse
.linuxtools
.tmf
.core
.event
.ITmfEvent
;
17 import org
.eclipse
.linuxtools
.tmf
.core
.event
.TmfTimeRange
;
18 import org
.eclipse
.linuxtools
.tmf
.core
.filter
.ITmfFilter
;
21 * The TMF request API.
23 * ITmfRequest:s are used to obtain blocks of events from an event provider. Open
24 * ranges can be used, typically for continuous streaming.
26 * The request is processed asynchronously by a TmfRequestHandler which invokes
27 * the request's handleEvent() synchronously for each event that matches the
30 * The TmfProvider indicates that the request is completed by calling done().
31 * The request can be canceled at any time with cancel(). In case of unexpected
32 * exception or error, fail() will be called.
37 * ITmfRequest request = new TmfRequest(someParams) {
39 * public synchronized void handleEvent(ITmfEvent event) {
40 * super.handleEvent(event);
44 * public void handleCompleted() {
48 * public void handleCancel() {
52 * public void handleFailure() {
56 * request.addEventFilter(myFilter);
57 * fProcessor.process(request);
61 * @author Francois Chouinard
65 public interface ITmfRequest
{
67 // ------------------------------------------------------------------------
69 // ------------------------------------------------------------------------
71 /** The request count for all the events */
72 public static final long ALL_EVENTS
= Long
.MAX_VALUE
;
74 // ------------------------------------------------------------------------
76 // ------------------------------------------------------------------------
79 * The request execution type/priority
82 public enum TmfRequestPriority
{
84 * Normal priority request (preemptible)
88 * High priority request (non-preemptible)
94 * The request execution state
97 public enum TmfRequestState
{
99 * The request is created but has not started being processed yet
103 * The request is being handled but has not completed yet
107 * The request has completed
112 // ------------------------------------------------------------------------
114 // ------------------------------------------------------------------------
117 * @return the request ID
119 public int getRequestId();
122 * @return the request type
124 public TmfRequestPriority
getRequestPriority();
127 * @return the time range of interest
129 public TmfTimeRange
getTimeRange();
132 * @return the number of events requested
134 public long getNbRequested();
137 * @return the index of the first event requested
139 public long getStartIndex();
142 * @return the number of events read so far
144 public long getNbEventsRead();
147 * @param filterType the filter type to retrieve
149 * @return the corresponding filter (if any)
151 public ITmfFilter
getEventFilter(Class
<?
> filterType
);
154 * Add/replace a filter
156 * @param filter the new filter
158 public void addEventFilter(ITmfFilter filter
);
161 * Check if the event matches the request
163 * @param event the event to test
165 * @return true if the event matches the request, false otherwise
167 public boolean matches(ITmfEvent event
);
170 * Sets the request's parent in the hierarchy
172 * @param parent the parent request
174 public void setParent(ITmfRequest parent
);
177 * Gets the request's parent in the hierarchy
179 * @return the parent request
181 public ITmfRequest
getParent();
184 * Completion notification for teh parent request
186 * @param child the child request
188 public void notifyParent(ITmfRequest child
);
190 // ------------------------------------------------------------------------
191 // Request execution state
192 // ------------------------------------------------------------------------
195 * @return the request execution state
197 public TmfRequestState
getState();
200 * @return true if the request is still active
202 public boolean isRunning();
205 * @return true if the request is completed
207 public boolean isCompleted();
209 // ------------------------------------------------------------------------
210 // Request completion status
211 // ------------------------------------------------------------------------
214 * @return the request completion status
216 public IStatus
getStatus();
219 * @return true if the request completed successfully
221 public boolean isOK();
225 * @return true if the request has failed */
226 public boolean isFailed();
229 * @return true if the request was cancelled
231 public boolean isCancelled();
233 // ------------------------------------------------------------------------
234 // Request operations
235 // ------------------------------------------------------------------------
238 * Put the request in the running state
243 * Put the request in the terminated state
248 * Put the request in the failed state
253 * Put the request in the cancelled state
255 public void cancel();
258 * To suspend the client thread until the request starts
261 * @throws InterruptedException thrown if the request was cancelled
263 public void waitForStart() throws InterruptedException
;
266 * To suspend the client thread until the request completes
269 * @throws InterruptedException thrown if the request was cancelled
271 public void waitForCompletion() throws InterruptedException
;
273 // ------------------------------------------------------------------------
274 // Request processing hooks
275 // ------------------------------------------------------------------------
278 * Request processing start notification
280 public void handleStarted();
283 * Process the piece of data
285 * @param event the data to process
287 public void handleEvent(ITmfEvent event
);
290 * Request processing completion notification
292 public void handleCompleted();
295 * Request successful completion notification
297 public void handleSuccess();
300 * Request failure notification
302 public void handleFailure();
305 * Request cancellation notification
307 public void handleCancel();
This page took 0.038024 seconds and 5 git commands to generate.