1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.vfs2;
18
19 import java.io.Closeable;
20 import java.io.DataInput;
21 import java.io.DataOutput;
22 import java.io.IOException;
23 import java.io.InputStream;
24
25 /**
26 * Provides random access over content.
27 */
28 public interface RandomAccessContent extends DataOutput, DataInput, Closeable {
29
30 /**
31 * Closes this random access file stream and releases any system resources associated with the stream.
32 * <p>
33 * A closed random access file cannot perform input or output operations and cannot be reopened.
34 * </p>
35 * <p>
36 * If this file has an associated channel then the channel is closed as well.
37 * </p>
38 *
39 * @throws IOException if an I/O error occurs.
40 */
41 @Override
42 void close() throws IOException;
43
44 /**
45 * Returns the current offset in this file.
46 *
47 * @return the offset from the beginning of the file, in bytes, at which the next read or write occurs.
48 * @throws IOException if an I/O error occurs.
49 */
50 long getFilePointer() throws IOException;
51
52 /**
53 * Get the input stream.
54 * <p>
55 * <b>Notice: If you use {@link #seek(long)} you have to re-get the InputStream</b>
56 * </p>
57 *
58 * @return the InputStream.
59 * @throws IOException if an I/O error occurs.
60 */
61 InputStream getInputStream() throws IOException;
62
63 /**
64 * Returns the length of this file.
65 *
66 * @return the length of this file, measured in bytes.
67 * @throws IOException if an I/O error occurs.
68 */
69 long length() throws IOException;
70
71 /**
72 * Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.
73 * <p>
74 * The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change
75 * the file length. The file length will change only by writing after the offset has been set beyond the end of the
76 * file.
77 * </p>
78 * <p>
79 * <b>Notice: If you use {@link #getInputStream()} you have to re-get the InputStream after calling
80 * {@link #seek(long)}</b>
81 * </p>
82 *
83 * @param pos the offset position, measured in bytes from the beginning of the file, at which to set the file
84 * pointer.
85 * @throws IOException if {@code pos} is less than {@code 0} or if an I/O error occurs.
86 */
87 void seek(long pos) throws IOException;
88
89 /**
90 * Sets the length of this content.
91 *
92 * <p>
93 * If the the {@code newLength} argument is smaller than {@link #length()}, the content is truncated.
94 * </p>
95 *
96 * <p>
97 * If the the {@code newLength} argument is greater than {@link #length()}, the content grows with undefined data.
98 * </p>
99 *
100 * @param newLength The desired content length
101 * @throws IOException If an I/O error occurs
102 * @since 2.1
103 */
104 void setLength(long newLength) throws IOException;
105
106 }