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.DataInput;
20  import java.io.DataOutput;
21  import java.io.IOException;
22  import java.io.InputStream;
23  
24  /**
25   * Provides random access over content.
26   */
27  public interface RandomAccessContent extends DataOutput, DataInput
28  {
29      /**
30       * Closes this random access file stream and releases any system resources associated with the stream.
31       * <p>
32       * A closed random access file cannot perform input or output operations and cannot be reopened.
33       * </p>
34       * <p>
35       * If this file has an associated channel then the channel is closed as well.
36       * <p>
37       *
38       * @throws IOException
39       *             if an I/O error occurs.
40       */
41      void close() throws IOException;
42  
43      /**
44       * Returns the current offset in this file.
45       *
46       * @return the offset from the beginning of the file, in bytes, at which the next read or write occurs.
47       * @throws IOException
48       *             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
60       *             if an I/O error occurs.
61       */
62      InputStream getInputStream() throws IOException;
63  
64      /**
65       * Returns the length of this file.
66       *
67       * @return the length of this file, measured in bytes.
68       * @throws IOException
69       *             if an I/O error occurs.
70       */
71      long length() throws IOException;
72  
73      /**
74       * Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.
75       * <p>
76       * The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change
77       * the file length. The file length will change only by writing after the offset has been set beyond the end of the
78       * file.
79       * </p>
80       * <p>
81       * <b>Notice: If you use {@link #getInputStream()} you have to re-get the InputStream after calling
82       * {@link #seek(long)}</b>
83       * </p>
84       *
85       * @param pos
86       *            the offset position, measured in bytes from the beginning of the file, at which to set the file
87       *            pointer.
88       * @throws IOException
89       *             if {@code pos} is less than {@code 0} or if an I/O error occurs.
90       */
91      void seek(long pos) throws IOException;
92  
93      /**
94       * Sets the length of this content.
95       *
96       * <p>
97       * If the the {@code newLength} argument is smaller than {@link #length()}, the content is truncated.
98       * </p>
99       *
100      * <p>
101      * If the the {@code newLength} argument is greater than {@link #length()}, the content grows with undefined data.
102      * </p>
103      *
104      * @param newLength
105      *            The desired content length
106      * @exception IOException
107      *                If an I/O error occurs
108      * @since 2.1
109      */
110     void setLength(long newLength) throws IOException;
111 
112 }