View Javadoc
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 }