org.eclipse.jetty.io.Buffer Maven / Gradle / Ivy
//
// ========================================================================
// Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd.
// ------------------------------------------------------------------------
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// and Apache License v2.0 which accompanies this distribution.
//
// The Eclipse Public License is available at
// http://www.eclipse.org/legal/epl-v10.html
//
// The Apache License v2.0 is available at
// http://www.opensource.org/licenses/apache2.0.php
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
//
package org.eclipse.jetty.io;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.charset.Charset;
/**
* Byte Buffer interface.
*
* This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different
* pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex.
*
* This buffer interface is designed to be similar, but not dependent on the java.nio buffers, which may
* be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have
* their valid _content before the position and a flip is required to access that data.
*
* For this buffer it is always true that:
* markValue <= getIndex <= putIndex <= capacity
*
*
* @version 1.0
*/
public interface Buffer extends Cloneable
{
public final static int
IMMUTABLE=0, // neither indexes or contexts can be changed
READONLY=1, // indexes may be changed, but not content
READWRITE=2; // anything can be changed
public final boolean VOLATILE=true; // The buffer may change outside of current scope.
public final boolean NON_VOLATILE=false;
/**
* Get the underlying array, if one exists.
* @return a byte[] backing this buffer or null if none exists.
*/
byte[] array();
/**
*
* @return a byte[] value of the bytes from the getIndex to the putIndex.
*/
byte[] asArray();
/**
* Get the underlying buffer. If this buffer wraps a backing buffer.
* @return The root backing buffer or this if there is no backing buffer;
*/
Buffer buffer();
/**
*
* @return a non volatile version of this Buffer value
*/
Buffer asNonVolatileBuffer();
/**
*
* @return a readonly version of this Buffer.
*/
Buffer asReadOnlyBuffer();
/**
*
* @return an immutable version of this Buffer.
*/
Buffer asImmutableBuffer();
/**
*
* @return an immutable version of this Buffer.
*/
Buffer asMutableBuffer();
/**
*
* The capacity of the buffer. This is the maximum putIndex that may be set.
* @return an int value
*/
int capacity();
/**
* the space remaining in the buffer.
* @return capacity - putIndex
*/
int space();
/**
* Clear the buffer. getIndex=0, putIndex=0.
*/
void clear();
/**
* Compact the buffer by discarding bytes before the postion (or mark if set).
* Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of
* the buffer and the values adjusted accordingly.
*/
void compact();
/**
* Get the byte at the current getIndex and increment it.
* @return The byte value from the current getIndex.
*/
byte get();
/**
* Get bytes from the current postion and put them into the passed byte array.
* The getIndex is incremented by the number of bytes copied into the array.
* @param b The byte array to fill.
* @param offset Offset in the array.
* @param length The max number of bytes to read.
* @return The number of bytes actually read.
*/
int get(byte[] b, int offset, int length);
/**
*
* @param length an int value
* @return a Buffer value
*/
Buffer get(int length);
/**
* The index within the buffer that will next be read or written.
* @return an int value >=0 <= putIndex()
*/
int getIndex();
/**
* @return true of putIndex > getIndex
*/
boolean hasContent();
/**
*
* @return a boolean value true if case sensitive comparison on this buffer
*/
boolean equalsIgnoreCase(Buffer buffer);
/**
*
* @return a boolean value true if the buffer is immutable and that neither
* the buffer contents nor the indexes may be changed.
*/
boolean isImmutable();
/**
*
* @return a boolean value true if the buffer is readonly. The buffer indexes may
* be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be
* read only.
*/
boolean isReadOnly();
/**
*
* @return a boolean value true if the buffer contents may change
* via alternate paths than this buffer. If the contents of this buffer are to be used outside of the
* current context, then a copy must be made.
*/
boolean isVolatile();
/**
* The number of bytes from the getIndex to the putIndex
* @return an int == putIndex()-getIndex()
*/
int length();
/**
* Set the mark to the current getIndex.
*/
void mark();
/**
* Set the mark relative to the current getIndex
* @param offset an int value to add to the current getIndex to obtain the mark value.
*/
void mark(int offset);
/**
* The current index of the mark.
* @return an int index in the buffer or -1 if the mark is not set.
*/
int markIndex();
/**
* Get the byte at the current getIndex without incrementing the getIndex.
* @return The byte value from the current getIndex.
*/
byte peek();
/**
* Get the byte at a specific index in the buffer.
* @param index an int value
* @return a byte value
*/
byte peek(int index);
/**
*
* @param index an int value
* @param length an int value
* @return The Buffer value from the requested getIndex.
*/
Buffer peek(int index, int length);
/**
*
* @param index an int value
* @param b The byte array to peek into
* @param offset The offset into the array to start peeking
* @param length an int value
* @return The number of bytes actually peeked
*/
int peek(int index, byte[] b, int offset, int length);
/**
* Put the contents of the buffer at the specific index.
* @param index an int value
* @param src a Buffer. If the source buffer is not modified
* @return The number of bytes actually poked
*/
int poke(int index, Buffer src);
/**
* Put a specific byte to a specific getIndex.
* @param index an int value
* @param b a byte value
*/
void poke(int index, byte b);
/**
* Put a specific byte to a specific getIndex.
* @param index an int value
* @param b a byte array value
* @return The number of bytes actually poked
*/
int poke(int index, byte b[], int offset, int length);
/**
* Write the bytes from the source buffer to the current getIndex.
* @param src The source Buffer it is not modified.
* @return The number of bytes actually poked
*/
int put(Buffer src);
/**
* Put a byte to the current getIndex and increment the getIndex.
* @param b a byte value
*/
void put(byte b);
/**
* Put a byte to the current getIndex and increment the getIndex.
* @param b a byte value
* @return The number of bytes actually poked
*/
int put(byte[] b,int offset, int length);
/**
* Put a byte to the current getIndex and increment the getIndex.
* @param b a byte value
* @return The number of bytes actually poked
*/
int put(byte[] b);
/**
* The index of the first element that should not be read.
* @return an int value >= getIndex()
*/
int putIndex();
/**
* Reset the current getIndex to the mark
*/
void reset();
/**
* Set the buffers start getIndex.
* @param newStart an int value
*/
void setGetIndex(int newStart);
/**
* Set a specific value for the mark.
* @param newMark an int value
*/
void setMarkIndex(int newMark);
/**
*
* @param newLimit an int value
*/
void setPutIndex(int newLimit);
/**
* Skip _content. The getIndex is updated by min(remaining(), n)
* @param n The number of bytes to skip
* @return the number of bytes skipped.
*/
int skip(int n);
/**
*
* @return a volitile Buffer from the postion to the putIndex.
*/
Buffer slice();
/**
*
*
* @return a volitile Buffer value from the mark to the putIndex
*/
Buffer sliceFromMark();
/**
*
*
* @param length an int value
* @return a valitile Buffer value from the mark of the length requested.
*/
Buffer sliceFromMark(int length);
/**
*
* @return a String value describing the state and contents of the buffer.
*/
String toDetailString();
/* ------------------------------------------------------------ */
/** Write the buffer's contents to the output stream
* @param out
*/
void writeTo(OutputStream out) throws IOException;
/* ------------------------------------------------------------ */
/** Read the buffer's contents from the input stream
* @param in input stream
* @param max maximum number of bytes that may be read
* @return actual number of bytes read or -1 for EOF
*/
int readFrom(InputStream in, int max) throws IOException;
/* ------------------------------------------------------------ */
String toString(String charset);
/* ------------------------------------------------------------ */
String toString(Charset charset);
/*
* Buffers implementing this interface should be compared with case insensitive equals
*
*/
public interface CaseInsensitve
{}
}