001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2010–2011 ApexIdentity Inc.
015 * Portions Copyright 2011-2015 ForgeRock AS.
016 */
017
018package org.forgerock.http.io;
019
020import java.io.Closeable;
021import java.io.IOException;
022
023/**
024 * A dynamically growing data buffer. Data can be read from any point within the buffer,
025 * and written to the end of a buffer.
026 */
027public interface Buffer extends Closeable {
028
029    /**
030     * Reads up to {@code len} bytes of data from the buffer into an array of bytes. An
031     * attempt is made to read as many as {@code len} bytes, but a smaller number may be read.
032     * The number of bytes actually read is returned as an integer.
033     *
034     * @param pos the offset position, measured in bytes from the beginning of the buffer, at which to read the data.
035     * @param b the array of bytes to write the data to.
036     * @param off the start offset in the array at which the data is written.
037     * @param len the maximum number of bytes to read.
038     * @return the number of bytes read into the array, or -1 if there is no more data.
039     * @throws IOException if an I/O exception occurs.
040     */
041    int read(int pos, byte[] b, int off, int len) throws IOException;
042
043    /**
044     * Appends {@code len} bytes from the specified byte array starting at offset {@code off}
045     * to the end of the buffer.
046     *
047     * @param b the array of bytes to read the data from.
048     * @param off the start offset in the array at which the data is read.
049     * @param len the number of bytes to be appended to the buffer.
050     * @throws IOException if an I/O exception occurs.
051     * @throws OverflowException if appending {@code len} bytes to the buffer would exceed its limit.
052     */
053    void append(byte[] b, int off, int len) throws IOException;
054
055    /**
056     * Returns the current length of the buffer.
057     *
058     * @return the length of the file, measured in bytes.
059     * @throws IOException if an I/O exception occurs.
060     */
061    int length() throws IOException;
062
063    /**
064     * Closes the buffer and releases any system resources associated with it. A closed buffer
065     * cannot perform input or output operations and cannot be reopened.
066     *
067     * @throws IOException if an I/O exception occurs.
068     */
069    @Override
070    void close() throws IOException;
071}