1 /*******************************************************************************
2 * Copyright (c) 2009, 2010 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
.request
;
15 import org
.eclipse
.linuxtools
.tmf
.event
.TmfData
;
18 * <b><u>TmfDataRequest</u></b>
20 * TmfDataRequests are used to obtain blocks of contiguous data from a data
21 * provider. Open ranges can be used, especially for continuous streaming.
23 * The request is processed asynchronously by a TmfProvider and, as blocks
24 * of data become available, handleData() is invoked synchronously for each
25 * block. Upon return, the data instances go out of scope and become eligible
26 * for gc. It is is thus the responsibility of the requester to either clone
27 * or keep a reference to the data it wishes to track specifically.
29 * This data block approach is used to avoid busting the heap for very
30 * large trace files. The block size is configurable.
32 * The TmfProvider indicates that the request is completed by calling done().
33 * The request can be canceled at any time with cancel().
36 *<pre><code><i>TmfTimeWindow range = new TmfTimewindow(...);
37 *TmfDataRequest<DataType[]> request = new TmfDataRequest<DataType[]>(DataType.class, 0, NB_EVENTS, BLOCK_SIZE) {
38 * public void handleData() {
39 * DataType[] data = request.getData();
40 * for (DataType e : data) {
44 * public void handleSuccess() {
48 * public void handleFailure() {
52 * public void handleCancel() {
57 *fProcessor.process(request, true);
60 * TODO: Consider decoupling from "time range", "rank", etc and for the more
61 * generic notion of "criteria". This would allow to extend for "time range", etc
62 * instead of providing specialized constructors. This also means removing the
63 * criteria info from the data structure (with the possible exception of fNbRequested).
64 * The nice thing about it is that it would prepare us well for the coming generation
67 * TODO: Implement request failures (codes, etc...)
69 public abstract class TmfDataRequest
<T
extends TmfData
> implements ITmfDataRequest
<T
> {
71 // ------------------------------------------------------------------------
73 // ------------------------------------------------------------------------
75 // The default maximum number of events per chunk
76 public static final int DEFAULT_BLOCK_SIZE
= 1000;
78 // The request count for all the events
79 public static final int ALL_DATA
= Integer
.MAX_VALUE
;
81 private static int fRequestNumber
= 0;
83 // ------------------------------------------------------------------------
85 // ------------------------------------------------------------------------
87 private final Class
<T
> fDataType
;
88 private final int fRequestId
; // A unique request ID
89 private final int fIndex
; // The index (rank) of the requested event
90 private final int fNbRequested
; // The number of requested events (ALL_DATA for all)
91 private final int fBlockSize
; // The maximum number of events per chunk
92 private int fNbRead
; // The number of reads so far
94 private Object lock
= new Object();
95 private boolean fRequestCompleted
= false;
96 private boolean fRequestFailed
= false;
97 private boolean fRequestCanceled
= false;
99 private T
[] fData
; // Data object
101 // ------------------------------------------------------------------------
103 // ------------------------------------------------------------------------
106 * Default constructor
108 public TmfDataRequest(Class
<T
> dataType
) {
109 this(dataType
, 0, ALL_DATA
, DEFAULT_BLOCK_SIZE
);
115 public TmfDataRequest(Class
<T
> dataType
, int index
) {
116 this(dataType
, index
, ALL_DATA
, DEFAULT_BLOCK_SIZE
);
123 public TmfDataRequest(Class
<T
> dataType
, int index
, int nbRequested
) {
124 this(dataType
, index
, nbRequested
, DEFAULT_BLOCK_SIZE
);
132 public TmfDataRequest(Class
<T
> dataType
, int index
, int nbRequested
, int blockSize
) {
133 fRequestId
= fRequestNumber
++;
134 fDataType
= dataType
;
136 fNbRequested
= nbRequested
;
137 fBlockSize
= blockSize
;
141 // ------------------------------------------------------------------------
143 // ------------------------------------------------------------------------
146 * @return the request ID
148 public long getRequestId() {
153 * @return the index of the first event requested
155 public int getIndex() {
160 * @return the number of requested events (ALL_DATA = all)
162 public int getNbRequested() {
167 * @return the block size
169 public int getBlockize() {
174 * @return the number of events read so far
176 public int getNbRead() {
181 * @return indicates if the request is completed
183 public boolean isCompleted() {
184 return fRequestCompleted
;
188 * @return indicates if the request is canceled
190 public boolean isFailed() {
191 return fRequestFailed
;
195 * @return indicates if the request is canceled
197 public boolean isCancelled() {
198 return fRequestCanceled
;
202 * @return the requested data type
204 public Class
<T
> getDataType() {
208 // ------------------------------------------------------------------------
210 // ------------------------------------------------------------------------
213 * Sets the data object to specified value. To be called by the
214 * asynchronous method implementor.
215 * @param data Data value to set.
217 public synchronized void setData(T
[] data
) {
218 fNbRead
+= data
.length
;
223 * Returns the data value, null if not set.
225 public synchronized T
[] getData() {
230 * Handle a block of incoming data. This method is called every time
231 * a block of data becomes available.
233 * - Data items are received in the order they appear in the stream.
234 * - Called by the request processor, in its execution thread, every time a
235 * block of data becomes available.
236 * - Request processor performs a synchronous call to handlePartialResult()
237 * i.e. its execution threads holds until handlePartialData() returns.
238 * - Original data items are disposed of on return i.e. keep a reference
239 * (or a copy) if some persistence is needed between invocations.
240 * - When there is no more data, done() is called.
242 * @param events - an array of events
244 public abstract void handleData();
247 * Handle the completion of the request. It is called when there is no more
248 * data available either because:
249 * - the request completed normally
250 * - the request failed
251 * - the request was canceled
253 * As a convenience, handleXXXX methods are provided. They are meant to be
254 * overridden by the application if it needs to handle these conditions.
256 public void handleCompleted() {
257 if (fRequestFailed
) {
260 else if (fRequestCanceled
) {
268 public void handleSuccess() {
271 public void handleFailure() {
274 public void handleCancel() {
278 * To suspend the client thread until the request completes (or is
281 * @throws InterruptedException
283 public void waitForCompletion() {
284 synchronized (lock
) {
285 while (!fRequestCompleted
)
288 } catch (InterruptedException e
) {
295 * Called by the request processor upon completion.
299 fRequestCompleted
= true;
306 * Called by the request processor upon failure.
310 fRequestFailed
= true;
316 * Called by the request processor upon cancellation.
318 public void cancel() {
320 fRequestCanceled
= true;
325 // ------------------------------------------------------------------------
327 // ------------------------------------------------------------------------
330 public int hashCode() {
335 public boolean equals(Object other
) {
336 if (other
instanceof TmfDataRequest
<?
>) {
337 TmfDataRequest
<?
> request
= (TmfDataRequest
<?
>) other
;
338 return (request
.fDataType
== fDataType
) &&
339 (request
.fIndex
== fIndex
) &&
340 (request
.fNbRequested
== fNbRequested
);
This page took 0.050085 seconds and 5 git commands to generate.