Source code: non_com/media/jai/codec/StreamSegmentMapper.java
1 /*
2 * Copyright (c) 2001 Sun Microsystems, Inc. All Rights Reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 *
7 * -Redistributions of source code must retain the above copyright notice, this
8 * list of conditions and the following disclaimer.
9 *
10 * -Redistribution in binary form must reproduct the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 *
14 * Neither the name of Sun Microsystems, Inc. or the names of contributors may
15 * be used to endorse or promote products derived from this software without
16 * specific prior written permission.
17 *
18 * This software is provided "AS IS," without a warranty of any kind. ALL
19 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
20 * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
21 * NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
22 * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
23 * OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
24 * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
25 * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
26 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
27 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
28 * POSSIBILITY OF SUCH DAMAGES.
29 *
30 * You acknowledge that Software is not designed,licensed or intended for use in
31 * the design, construction, operation or maintenance of any nuclear facility.
32 */
33 package non_com.media.jai.codec;
34 /**
35 * An interface for use with the <code>SegmentedSeekableStream</code> class. An
36 * instance of the <code>StreamSegmentMapper</code> interface provides the
37 * location and length of a segment of a source <code>SeekableStream</code>
38 * corresponding to the initial portion of a desired segment of the output
39 * stream. <p>
40 *
41 * As an example, consider a mapping between a source <code>SeekableStream src</code>
42 * and a <code>SegmentedSeekableStream
43 * dst</code> comprising bytes 100-149 and 200-249 of the source stream. The
44 * <code>dst</code> stream has a reference to an instance <code>mapper</code>
45 * of <code>StreamSegmentMapper</code>. <p>
46 *
47 * A call to <code>dst.seek(0); dst.read(buf, 0, 10)</code> will result in a
48 * call to <code>mapper.getStreamSegment(0, 10)</code>, returning a new <code>StreamSegment</code>
49 * with a starting position of 100 and a length of 10 (or less). This indicates
50 * that in order to read bytes 0-9 of the segmented stream, bytes 100-109 of
51 * the source stream should be read. <p>
52 *
53 * A call to <code>dst.seek(10); int nbytes = dst.read(buf, 0,
54 * 100)</code> is somewhat more complex, since it will require data from both
55 * segments of <code>src</code>. The method <code>
56 * mapper.getStreamSegment(10, 100)</code> will be called. This method will
57 * return a new <code>StreamSegment</code> with a starting position of 110 and
58 * a length of 40 (or less). The length is limited to 40 since a longer value
59 * would result in a read past the end of the first segment. The read will stop
60 * after the first 40 bytes and an addition read or reads will be required to
61 * obtain the data contained in the second segment. <p>
62 *
63 * <b> This interface is not a committed part of the JAI API. It may be removed
64 * or changed in future releases of JAI.</b>
65 *
66 */
67 public interface StreamSegmentMapper {
68
69 /**
70 * Returns a <code>StreamSegment</code> object indicating the location of the
71 * initial portion of a desired segment in the source stream. The length of
72 * the returned <code>StreamSegment</code> may be smaller than the desired
73 * length.
74 *
75 * @param pos The desired starting position in the <code>SegmentedSeekableStream</code>
76 * , as a <code>long</code>.
77 * @param length The desired segment length.
78 * @return The StreamSegment value
79 */
80 StreamSegment getStreamSegment(long pos, int length);
81
82
83 /**
84 * Sets the values of a <code>StreamSegment</code> object indicating the
85 * location of the initial portion of a desired segment in the source stream.
86 * The length of the returned <code>StreamSegment</code> may be smaller than
87 * the desired length.
88 *
89 * @param pos The desired starting position in the <code>SegmentedSeekableStream</code>
90 * , as a <code>long</code>.
91 * @param length The desired segment length.
92 * @param seg A <code>StreamSegment</code> object to be overwritten.
93 */
94 void getStreamSegment(long pos, int length, StreamSegment seg);
95 }