01: /*
02: * $RCSfile: StreamSegmentMapper.java,v $
03: *
04: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
05: *
06: * Use is subject to license terms.
07: *
08: * $Revision: 1.1 $
09: * $Date: 2005/02/11 04:55:33 $
10: * $State: Exp $
11: */
12: package com.sun.media.jai.codec;
13:
14: /**
15: * An interface for use with the <code>SegmentedSeekableStream</code>
16: * class. An instance of the <code>StreamSegmentMapper</code>
17: * interface provides the location and length of a segment of a source
18: * <code>SeekableStream</code> corresponding to the initial portion of
19: * a desired segment of the output stream.
20: *
21: * <p> As an example, consider a mapping between a source
22: * <code>SeekableStream src</code> and a <code>SegmentedSeekableStream
23: * dst</code> comprising bytes 100-149 and 200-249 of the source
24: * stream. The <code>dst</code> stream has a reference to an instance
25: * <code>mapper</code> of <code>StreamSegmentMapper</code>.
26: *
27: * <p> A call to <code>dst.seek(0); dst.read(buf, 0, 10)</code> will
28: * result in a call to <code>mapper.getStreamSegment(0, 10)</code>,
29: * returning a new <code>StreamSegment</code> with a starting
30: * position of 100 and a length of 10 (or less). This indicates that
31: * in order to read bytes 0-9 of the segmented stream, bytes 100-109
32: * of the source stream should be read.
33: *
34: * <p> A call to <code>dst.seek(10); int nbytes = dst.read(buf, 0,
35: * 100)</code> is somewhat more complex, since it will require data
36: * from both segments of <code>src</code>. The method <code>
37: * mapper.getStreamSegment(10, 100)</code> will be called. This
38: * method will return a new <code>StreamSegment</code> with a starting
39: * position of 110 and a length of 40 (or less). The length is
40: * limited to 40 since a longer value would result in a read past the
41: * end of the first segment. The read will stop after the first 40
42: * bytes and an addition read or reads will be required to obtain the
43: * data contained in the second segment.
44: *
45: * <p><b> This interface is not a committed part of the JAI API. It may
46: * be removed or changed in future releases of JAI.</b>
47: */
48: public interface StreamSegmentMapper {
49:
50: /**
51: * Returns a <code>StreamSegment</code> object indicating the
52: * location of the initial portion of a desired segment in the
53: * source stream. The length of the returned
54: * <code>StreamSegment</code> may be smaller than the desired
55: * length.
56: *
57: * @param pos The desired starting position in the
58: * <code>SegmentedSeekableStream</code>, as a <code>long</code>.
59: * @param length The desired segment length.
60: */
61: StreamSegment getStreamSegment(long pos, int length);
62:
63: /**
64: * Sets the values of a <code>StreamSegment</code> object
65: * indicating the location of the initial portion of a desired
66: * segment in the source stream. The length of the returned
67: * <code>StreamSegment</code> may be smaller than the desired
68: * length.
69: *
70: * @param pos The desired starting position in the
71: * <code>SegmentedSeekableStream</code>, as a <code>long</code>.
72: * @param length The desired segment length.
73: * @param seg A <code>StreamSegment</code> object to be overwritten.
74: */
75: void getStreamSegment(long pos, int length, StreamSegment seg);
76: }
|