001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.vfs2; 018 019import java.io.DataInput; 020import java.io.DataOutput; 021import java.io.IOException; 022import java.io.InputStream; 023 024/** 025 * Provides random access over content. 026 */ 027public interface RandomAccessContent extends DataOutput, DataInput { 028 /** 029 * Closes this random access file stream and releases any system resources associated with the stream. 030 * <p> 031 * A closed random access file cannot perform input or output operations and cannot be reopened. 032 * </p> 033 * <p> 034 * If this file has an associated channel then the channel is closed as well. 035 * <p> 036 * 037 * @throws IOException if an I/O error occurs. 038 */ 039 void close() throws IOException; 040 041 /** 042 * Returns the current offset in this file. 043 * 044 * @return the offset from the beginning of the file, in bytes, at which the next read or write occurs. 045 * @throws IOException if an I/O error occurs. 046 */ 047 long getFilePointer() throws IOException; 048 049 /** 050 * Get the input stream. 051 * <p> 052 * <b>Notice: If you use {@link #seek(long)} you have to re-get the InputStream</b> 053 * </p> 054 * 055 * @return the InputStream. 056 * @throws IOException if an I/O error occurs. 057 */ 058 InputStream getInputStream() throws IOException; 059 060 /** 061 * Returns the length of this file. 062 * 063 * @return the length of this file, measured in bytes. 064 * @throws IOException if an I/O error occurs. 065 */ 066 long length() throws IOException; 067 068 /** 069 * Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs. 070 * <p> 071 * The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change 072 * the file length. The file length will change only by writing after the offset has been set beyond the end of the 073 * file. 074 * </p> 075 * <p> 076 * <b>Notice: If you use {@link #getInputStream()} you have to re-get the InputStream after calling 077 * {@link #seek(long)}</b> 078 * </p> 079 * 080 * @param pos the offset position, measured in bytes from the beginning of the file, at which to set the file 081 * pointer. 082 * @throws IOException if {@code pos} is less than {@code 0} or if an I/O error occurs. 083 */ 084 void seek(long pos) throws IOException; 085 086 /** 087 * Sets the length of this content. 088 * 089 * <p> 090 * If the the {@code newLength} argument is smaller than {@link #length()}, the content is truncated. 091 * </p> 092 * 093 * <p> 094 * If the the {@code newLength} argument is greater than {@link #length()}, the content grows with undefined data. 095 * </p> 096 * 097 * @param newLength The desired content length 098 * @throws IOException If an I/O error occurs 099 * @since 2.1 100 */ 101 void setLength(long newLength) throws IOException; 102 103}