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}