001 package jigcell.compare;
002
003 import java.awt.datatransfer.Transferable;
004 import java.io.Serializable;
005 import java.text.NumberFormat;
006
007 /**
008 * This interface is implemented by classes that wish to provide a data element to the comparator. An element can either be a list of one or
009 * more elements or a scalar. When viewed as a list, a scalar element has value only at the 0th list position; a list element of n elements
010 * has values at the 1st through nth list positions.
011 *
012 * <p>
013 * This code is licensed under the DARPA BioCOMP Open Source License. See LICENSE for more details.
014 * </p>
015 *
016 * @author Nicholas Allen
017 */
018
019 public interface IDataElement extends Serializable, Transferable {
020
021 /**
022 * The types of a data element.
023 */
024
025 final class Type {
026
027 /**
028 * A scalar value that is either true or false
029 */
030
031 public final static Type BOOLEAN = new Type ("BOOLEAN");
032
033 /**
034 * A scalar value contained in the integers
035 */
036
037 public final static Type INTEGRAL = new Type ("INTEGRAL");
038
039 /**
040 * A scalar value that is a string literal
041 */
042
043 public final static Type LITERAL = new Type ("LITERAL");
044
045 /**
046 * A non-scalar value
047 */
048
049 public final static Type MULTIPLE = new Type ("MULTIPLE");
050
051 /**
052 * A non-value
053 */
054
055 public final static Type NONE = new Type ("NONE");
056
057 /**
058 * A scalar value contained in the reals
059 */
060
061 public final static Type REAL = new Type ("REAL");
062
063 /**
064 * Name of this type
065 */
066
067 private final String name;
068
069 public String toString () {
070 return name;
071 }
072
073 /**
074 * Creates a new data element type.
075 *
076 * @param name Display name
077 */
078
079 private Type (String name) {
080 this.name = name;
081 }
082 }
083
084 /**
085 * This element represented as a boolean when evaluated in a scalar context. If this element is not a boolean it is suitably coerced.
086 */
087
088 boolean forceBooleanValue ();
089
090 /**
091 * The element at position pos represented as a boolean. If the given position is not a boolean it is suitably coerced.
092 *
093 * @param pos Position
094 */
095
096 boolean forceBooleanValue (long pos);
097
098 /**
099 * This element represented as an integer when evaluated in a scalar context. If this element is not an integer it is suitably coerced.
100 */
101
102 long forceIntegralValue ();
103
104 /**
105 * The element at position pos represented as an integer. If the given position is not an integer it is suitably coerced.
106 *
107 * @param pos Position
108 */
109
110 long forceIntegralValue (long pos);
111
112 /**
113 * This element at position pos represented as a list. If the given position is not a list it is suitably coerced.
114 *
115 * @param pos Position
116 */
117
118 IDataElement forceListValue (long pos);
119
120 /**
121 * This element represented as a string literal when evaluated in a scalar context. If this element is not a string literal it is suitably
122 * coerced.
123 */
124
125 String forceLiteralValue ();
126
127 /**
128 * The element at position pos represented as a string literal. If the given position is not a string literal it is suitably coerced.
129 *
130 * @param pos Position
131 */
132
133 String forceLiteralValue (long pos);
134
135 /**
136 * This element represented as a real when evaluated in a scalar context. If this element is not a real it is suitably coerced.
137 */
138
139 double forceRealValue ();
140
141 /**
142 * The element at position pos represented as a real. If the given position is not a real it is suitably coerced.
143 *
144 * @param pos Position
145 */
146
147 double forceRealValue (long pos);
148
149 /**
150 * A dense, homogeneous subset of this element represented as a boolean list. If slice cannot hold the requested range, a new array is
151 * created and returned. Slice may be null. If the given length has no valid meaning, the value is null. Elements not of type boolean are
152 * suitably coerced. Past the defined range of the list, all values are considered false. Position 0 in the returned slice corresponds to
153 * position start in the original element.
154 *
155 * @param slice Suggested container for the slice
156 * @param start First position to pull
157 * @param length Number of positions to pull
158 * @param stride Interval between positions to pull
159 */
160
161 boolean [] forceSlice (boolean slice [], long start, int length, long stride);
162
163 /**
164 * A dense, homogeneous subset of this element represented as a list of elements. If slice cannot hold the requested range, a new array is
165 * created and returned. Slice may be null. If the given length has no valid meaning, the value is null. Elements not of type list are
166 * suitably coerced. Past the defined range of the list, all values are considered scalars of no type. Position 0 in the returned slice
167 * corresponds to position start in the original element.
168 *
169 * @param slice Suggested container for the slice
170 * @param start First position to pull
171 * @param length Number of positions to pull
172 * @param stride Interval between positions to pull
173 */
174
175 IDataElement [] forceSlice (IDataElement slice [], long start, int length, long stride);
176
177 /**
178 * A dense, homogeneous subset of this element represented as a real list. If slice cannot hold the requested range, a new array is created
179 * and returned. Slice may be null. If the given length has no valid meaning, the value is null. Elements not of type real are suitably
180 * coerced. Past the defined range of the list, all values are considered NaN. Position 0 in the returned slice corresponds to position
181 * start in the original element.
182 *
183 * @param slice Suggested container for the slice
184 * @param start First position to pull
185 * @param length Number of positions to pull
186 * @param stride Interval between positions to pull
187 */
188
189 double [] forceSlice (double slice [], long start, int length, long stride);
190
191 /**
192 * A dense, homogeneous subset of this element represented as an integral list. If slice cannot hold the requested range, a new array is
193 * created and returned. Slice may be null. If the given length has no valid meaning, the value is null. Elements not of type integral
194 * are suitably coerced. Past the defined range of the list, all values are considered 0. Position 0 in the returned slice corresponds to
195 * position start in the original element.
196 *
197 * @param slice Suggested container for the slice
198 * @param start First position to pull
199 * @param length Number of positions to pull
200 * @param stride Interval between positions to pull
201 */
202
203 long [] forceSlice (long slice [], long start, int length, long stride);
204
205 /**
206 * A dense, homogeneous subset of this element represented as a string literal list. If slice cannot hold the requested range, a new array
207 * is created and returned. Slice may be null. If the given length has no valid meaning, the value is null. Elements not of type string
208 * literal are suitably coerced. Past the defined range of the list, all values are considered null. Position 0 in the returned slice
209 * corresponds to position start in the original element.
210 *
211 * @param slice Suggested container for the slice
212 * @param start First position to pull
213 * @param length Number of positions to pull
214 * @param stride Interval between positions to pull
215 */
216
217 String [] forceSlice (String slice [], long start, int length, long stride);
218
219 /**
220 * This element represented as a boolean when evaluated in a scalar context.
221 */
222
223 boolean getBooleanValue ();
224
225 /**
226 * The element at position pos represented as a boolean. If the given position has no valid meaning for this element, the value is false.
227 *
228 * @param pos Position
229 */
230
231 boolean getBooleanValue (long pos);
232
233 /**
234 * This element represented as an integer when evaluated in a scalar context.
235 */
236
237 long getIntegralValue ();
238
239 /**
240 * The element at position pos represented as an integer. If the given position has no valid meaning for this element, the value is 0.
241 *
242 * @param pos Position
243 */
244
245 long getIntegralValue (long pos);
246
247 /**
248 * The number of elements in this element, or 0 if this element is scalar.
249 */
250
251 long getLength ();
252
253 /**
254 * This element at position pos represented as a list. If the given position has no valid meaning for this element, the value is null.
255 *
256 * @param pos Position
257 */
258
259 IDataElement getListValue (long pos);
260
261 /**
262 * This element represented as a string literal when evaluated in a scalar context. The literal is not quoted.
263 */
264
265 String getLiteralValue ();
266
267 /**
268 * The element at position pos represented as a string literal. If the given position has no valid meaning for this element, the value is
269 * null. The literal is not quoted.
270 *
271 * @param pos Position
272 */
273
274 String getLiteralValue (long pos);
275
276 /**
277 * This element represented as a real when evaluated in a scalar context.
278 */
279
280 double getRealValue ();
281
282 /**
283 * The element at position pos represented as a real. If the given position has no valid meaning for this element, the value is NaN.
284 *
285 * @param pos Position
286 */
287
288 double getRealValue (long pos);
289
290 /**
291 * A dense, homogeneous subset of this element represented as a boolean list. If slice cannot hold the requested range, a new array is
292 * created and returned. Slice may be null. If the given start or length has no valid meaning for this element, the value is null. If the
293 * subset is not a dense list of booleans or slices are not available, the value is null. Position 0 in the returned slice corresponds to
294 * position start in the original element.
295 *
296 * @param slice Suggested container for the slice
297 * @param start First position to pull
298 * @param length Number of positions to pull
299 * @param stride Interval between positions to pull
300 */
301
302 boolean [] getSlice (boolean slice [], long start, int length, long stride);
303
304 /**
305 * A dense, homogeneous subset of this element represented as a list of elements. If slice cannot hold the requested range, a new array is
306 * created and returned. Slice may be null. If the given start or length has no valid meaning for this element, the value is null. If the
307 * subset is not a dense list of lists or slices are not available, the value is null. Position 0 in the returned slice corresponds to
308 * position start in the original element.
309 *
310 * @param slice Suggested container for the slice
311 * @param start First position to pull
312 * @param length Number of positions to pull
313 * @param stride Interval between positions to pull
314 */
315
316 IDataElement [] getSlice (IDataElement slice [], long start, int length, long stride);
317
318 /**
319 * A dense, homogeneous subset of this element represented as a real list. If slice cannot hold the requested range, a new array is created
320 * and returned. Slice may be null. If the given start or length has no valid meaning for this element, the value is null. If the subset
321 * is not a dense list of reals or slices are not available, the value is null. Position 0 in the returned slice corresponds to position
322 * start in the original element.
323 *
324 * @param slice Suggested container for the slice
325 * @param start First position to pull
326 * @param length Number of positions to pull
327 * @param stride Interval between positions to pull
328 */
329
330 double [] getSlice (double slice [], long start, int length, long stride);
331
332 /**
333 * A dense, homogeneous subset of this element represented as an integral list. If slice cannot hold the requested range, a new array is
334 * created and returned. Slice may be null. If the given start or length has no valid meaning for this element, the value is null. If the
335 * subset is not a dense list of integers or slices are not available, the value is null. Position 0 in the returned slice corresponds to
336 * position start in the original element.
337 *
338 * @param slice Suggested container for the slice
339 * @param start First position to pull
340 * @param length Number of positions to pull
341 * @param stride Interval between positions to pull
342 */
343
344 long [] getSlice (long slice [], long start, int length, long stride);
345
346 /**
347 * A dense, homogeneous subset of this element represented as a string literal list. If slice cannot hold the requested range, a new array
348 * is created and returned. Slice may be null. If the given start or length has no valid meaning for this element, the value is null. If
349 * the subset is not a dense list of string literals or slices are not available, the value is null. Position 0 in the returned slice
350 * corresponds to position start in the original element.
351 *
352 * @param slice Suggested container for the slice
353 * @param start First position to pull
354 * @param length Number of positions to pull
355 * @param stride Interval between positions to pull
356 */
357
358 String [] getSlice (String slice [], long start, int length, long stride);
359
360 /**
361 * The type of this element.
362 */
363
364 IDataElement.Type getType ();
365
366 /**
367 * The type of the element at position pos. If the given position has no valid meaning for this object, the type is TYPE_NONE.
368 *
369 * @param pos Position
370 */
371
372 IDataElement.Type getType (long pos);
373
374 /**
375 * Whether the element data can currently be worked with. Editing the internal state of a data generator while locked may cause subsequent
376 * calls to isAvailable to incorrectly report that the element data is available.
377 */
378
379 boolean isAvailable ();
380
381 /**
382 * Whether this element is scalar.
383 */
384
385 boolean isScalar ();
386
387 /**
388 * Forces the element to guarantee that the element data can currently be worked with. Implementations may or may not support reentrancy or
389 * other forms of multiple locking. Editing the internal state of a data generator while locked may cause subsequent calls to memoryLock to
390 * incorrectly terminate without guarantee that the element data can currently be worked with.
391 */
392
393 void memoryLock ();
394
395 /**
396 * Releases the element from the guarantee that the element data can currently be worked with. Implementations may or may not support
397 * reentrancy or other forms of multiple locking.
398 */
399
400 void memoryUnlock ();
401
402 /**
403 * Renders the value with a particular format.
404 *
405 * @param format Format
406 */
407
408 String toString (NumberFormat format);
409
410 /**
411 * Renders the value of a specified position.
412 *
413 * @param pos Render position
414 */
415
416 String toString (long pos);
417
418 /**
419 * Renders the DataElement as an ordered tuple.
420 *
421 * @param limit Whether to abbreviate the string.
422 * @param size Approximate length before abbreviation occurs.
423 */
424
425 String toString (boolean limit, int size);
426
427 /**
428 * Renders the value of a specified position with a particular format.
429 *
430 * @param pos Render position
431 * @param format Format
432 */
433
434 String toString (long pos, NumberFormat format);
435
436 /**
437 * Renders the DataElement as an ordered tuple with a particular format.
438 *
439 * @param limit Whether to abbreviate the string.
440 * @param size Approximate length before abbreviation occurs.
441 * @param format Format
442 */
443
444 String toString (boolean limit, int size, NumberFormat format);
445
446 /**
447 * Renders the value of a specified position.
448 *
449 * @param limit Whether to abbreviate the string.
450 * @param size Approximate length before abbreviation occurs.
451 * @param pos Render position
452 */
453
454 String toString (boolean limit, int size, long pos);
455
456 /**
457 * Renders the value of a specified position with a particular format.
458 *
459 * @param limit Whether to abbreviate the string.
460 * @param size Approximate length before abbreviation occurs.
461 * @param pos Render position
462 * @param format Format
463 */
464
465 String toString (boolean limit, int size, long pos, NumberFormat format);
466 }