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-2014 ForgeRock AS. 016 */ 017 018package org.forgerock.openig.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, OverflowException; 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}