View Javadoc

    1   // ========================================================================
    2   // Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
    3   // ------------------------------------------------------------------------
    4   // Licensed under the Apache License, Version 2.0 (the "License");
    5   // you may not use this file except in compliance with the License.
    6   // You may obtain a copy of the License at
    7   // http://www.apache.org/licenses/LICENSE-2.0
    8   // Unless required by applicable law or agreed to in writing, software
    9   // distributed under the License is distributed on an "AS IS" BASIS,
    10  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    11  // See the License for the specific language governing permissions and
    12  // limitations under the License.
    13  // ========================================================================
    14
    15  package org.mortbay.io;
    16
    17  import java.io.IOException;
    18  import java.io.InputStream;
    19  import java.io.OutputStream;
    20
    21
    22  /**
    23   * Byte Buffer interface.
    24   *
    25   * This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different
    26   * pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex.
    27   *
    28   * This buffer interface is designed to be similar, but not dependant on the java.nio buffers, which may
    29   * be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have
    30   * their valid _content before the position and a flip is required to access that data.
    31   *
    32   * For this buffer it is always true that:
    33   *  markValue <= getIndex <= putIndex <= capacity
    34   *  @author gregw
    35   *
    36   * @version 1.0
    37   */
    38  public interface Buffer extends Cloneable
    39  {
    40      public final static int
    41        IMMUTABLE=0,  // neither indexes or contexts can be changed
    42        READONLY=1,   // indexes may be changed, but not content
    43        READWRITE=2;  // anything can be changed
    44      public final boolean VOLATILE=true;     // The buffer may change outside of current scope.
    45      public final boolean NON_VOLATILE=false;
    46
    47      /**
    48       *  Get the underlying array, if one exists.
    49       * @return a <code>byte[]</code> backing this buffer or null if none exists.
    50       */
    51      byte[] array();
    52
    53      /**
    54       *
    55       * @return a <code>byte[]</code> value of the bytes from the getIndex to the putIndex.
    56       */
    57      byte[] asArray();
    58
    59      /**
    60       * Get the unerlying buffer. If this buffer wraps a backing buffer.
    61       * @return The root backing buffer or this if there is no backing buffer;
    62       */
    63      Buffer buffer();
    64
    65      /**
    66       *
    67       * @return a non volitile version of this <code>Buffer</code> value
    68       */
    69      Buffer asNonVolatileBuffer();
    70
    71      /**
    72       *
    73       * @return a readonly version of this <code>Buffer</code>.
    74       */
    75      Buffer asReadOnlyBuffer();
    76
    77      /**
    78       *
    79       * @return an immutable version of this <code>Buffer</code>.
    80       */
    81      Buffer asImmutableBuffer();
    82
    83      /**
    84       *
    85       * @return an immutable version of this <code>Buffer</code>.
    86       */
    87      Buffer asMutableBuffer();
    88
    89      /**
    90       *
    91       * The capacity of the buffer. This is the maximum putIndex that may be set.
    92       * @return an <code>int</code> value
    93       */
    94      int capacity();
    95
    96      /**
    97       * the space remaining in the buffer.
    98       * @return capacity - putIndex
    99       */
    100     int space();
    101
    102     /**
    103      * Clear the buffer. getIndex=0, putIndex=0.
    104      */
    105     void clear();
    106
    107     /**
    108      * Compact the buffer by discarding bytes before the postion (or mark if set).
    109      * Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of
    110      * the buffer and the values adjusted accordingly.
    111      */
    112     void compact();
    113
    114     /**
    115      * Get the byte at the current getIndex and increment it.
    116      * @return The <code>byte</code> value from the current getIndex.
    117      */
    118     byte get();
    119
    120     /**
    121      * Get bytes from the current postion and put them into the passed byte array.
    122      * The getIndex is incremented by the number of bytes copied into the array.
    123      * @param b The byte array to fill.
    124      * @param offset Offset in the array.
    125      * @param length The max number of bytes to read.
    126      * @return The number of bytes actually read.
    127      */
    128     int get(byte[] b, int offset, int length);
    129
    130     /**
    131      *
    132      * @param length an <code>int</code> value
    133      * @return a <code>Buffer</code> value
    134      */
    135     Buffer get(int length);
    136
    137     /**
    138      * The index within the buffer that will next be read or written.
    139      * @return an <code>int</code> value >=0 <= putIndex()
    140      */
    141     int getIndex();
    142
    143     /**
    144      * @return true of putIndex > getIndex
    145      */
    146     boolean hasContent();
    147
    148     /**
    149      *
    150      * @return a <code>boolean</code> value true if case sensitive comparison on this buffer
    151      */
    152     boolean equalsIgnoreCase(Buffer buffer);
    153
    154
    155     /**
    156      *
    157      * @return a <code>boolean</code> value true if the buffer is immutable and that neither
    158      * the buffer contents nor the indexes may be changed.
    159      */
    160     boolean isImmutable();
    161
    162     /**
    163      *
    164      * @return a <code>boolean</code> value true if the buffer is readonly. The buffer indexes may
    165      * be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be
    166      * read only.
    167      */
    168     boolean isReadOnly();
    169
    170     /**
    171      *
    172      * @return a <code>boolean</code> value true if the buffer contents may change
    173      * via alternate paths than this buffer.  If the contents of this buffer are to be used outside of the
    174      * current context, then a copy must be made.
    175      */
    176     boolean isVolatile();
    177
    178     /**
    179      * The number of bytes from the getIndex to the putIndex
    180      * @return an <code>int</code> == putIndex()-getIndex()
    181      */
    182     int length();
    183
    184     /**
    185      * Set the mark to the current getIndex.
    186      */
    187     void mark();
    188
    189     /**
    190      * Set the mark relative to the current getIndex
    191      * @param offset an <code>int</code> value to add to the current getIndex to obtain the mark value.
    192      */
    193     void mark(int offset);
    194
    195     /**
    196      * The current index of the mark.
    197      * @return an <code>int</code> index in the buffer or -1 if the mark is not set.
    198      */
    199     int markIndex();
    200
    201     /**
    202      * Get the byte at the current getIndex without incrementing the getIndex.
    203      * @return The <code>byte</code> value from the current getIndex.
    204      */
    205     byte peek();
    206
    207     /**
    208      * Get the byte at a specific index in the buffer.
    209      * @param index an <code>int</code> value
    210      * @return a <code>byte</code> value
    211      */
    212     byte peek(int index);
    213
    214     /**
    215      *
    216      * @param index an <code>int</code> value
    217      * @param length an <code>int</code> value
    218      * @return The <code>Buffer</code> value from the requested getIndex.
    219      */
    220     Buffer peek(int index, int length);
    221
    222     /**
    223      *
    224      * @param index an <code>int</code> value
    225      * @param b The byte array to peek into
    226      * @param offset The offset into the array to start peeking
    227      * @param length an <code>int</code> value
    228      * @return The number of bytes actually peeked
    229      */
    230     int peek(int index, byte[] b, int offset, int length);
    231
    232     /**
    233      * Put the contents of the buffer at the specific index.
    234      * @param index an <code>int</code> value
    235      * @param src a <code>Buffer</code>. If the source buffer is not modified
    236
    237      * @return The number of bytes actually poked
    238      */
    239     int poke(int index, Buffer src);
    240
    241     /**
    242      * Put a specific byte to a specific getIndex.
    243      * @param index an <code>int</code> value
    244      * @param b a <code>byte</code> value
    245      */
    246     void poke(int index, byte b);
    247
    248     /**
    249      * Put a specific byte to a specific getIndex.
    250      * @param index an <code>int</code> value
    251      * @param b a <code>byte array</code> value
    252      * @return The number of bytes actually poked
    253      */
    254     int poke(int index, byte b[], int offset, int length);
    255
    256     /**
    257      * Write the bytes from the source buffer to the current getIndex.
    258      * @param src The source <code>Buffer</code> it is not modified.
    259      * @return The number of bytes actually poked
    260      */
    261     int put(Buffer src);
    262
    263     /**
    264      * Put a byte to the current getIndex and increment the getIndex.
    265      * @param b a <code>byte</code> value
    266      */
    267     void put(byte b);
    268
    269     /**
    270      * Put a byte to the current getIndex and increment the getIndex.
    271      * @param b a <code>byte</code> value
    272      * @return The number of bytes actually poked
    273      */
    274     int put(byte[] b,int offset, int length);
    275
    276     /**
    277      * Put a byte to the current getIndex and increment the getIndex.
    278      * @param b a <code>byte</code> value
    279      * @return The number of bytes actually poked
    280      */
    281     int put(byte[] b);
    282
    283     /**
    284      * The index of the first element that should not be read.
    285      * @return an <code>int</code> value >= getIndex()
    286      */
    287     int putIndex();
    288
    289     /**
    290      * Reset the current getIndex to the mark
    291      */
    292     void reset();
    293
    294     /**
    295      * Set the buffers start getIndex.
    296      * @param newStart an <code>int</code> value
    297      */
    298     void setGetIndex(int newStart);
    299
    300     /**
    301      * Set a specific value for the mark.
    302      * @param newMark an <code>int</code> value
    303      */
    304     void setMarkIndex(int newMark);
    305
    306     /**
    307      *
    308      * @param newLimit an <code>int</code> value
    309      */
    310     void setPutIndex(int newLimit);
    311
    312     /**
    313      * Skip _content. The getIndex is updated by min(remaining(), n)
    314      * @param n The number of bytes to skip
    315      * @return the number of bytes skipped.
    316      */
    317     int skip(int n);
    318
    319     /**
    320      *
    321      * @return a volitile <code>Buffer</code> from the postion to the putIndex.
    322      */
    323     Buffer slice();
    324
    325     /**
    326      *
    327      *
    328      * @return a volitile <code>Buffer</code> value from the mark to the putIndex
    329      */
    330     Buffer sliceFromMark();
    331
    332     /**
    333      *
    334      *
    335      * @param length an <code>int</code> value
    336      * @return a valitile <code>Buffer</code> value from the mark of the length requested.
    337      */
    338     Buffer sliceFromMark(int length);
    339
    340     /**
    341      *
    342      * @return a <code>String</code> value describing the state and contents of the buffer.
    343      */
    344     String toDetailString();
    345
    346     /* ------------------------------------------------------------ */
    347     /** Write the buffer's contents to the output stream
    348      * @param out
    349      */
    350     void writeTo(OutputStream out) throws IOException;
    351
    352     /* ------------------------------------------------------------ */
    353     /** Read the buffer's contents from the input stream
    354      * @param in input stream
    355      * @param max maximum number of bytes that may be read
    356      * @return actual number of bytes read or -1 for EOF
    357      */
    358     int readFrom(InputStream in, int max) throws IOException;
    359
    360
    361
    362     /*
    363      * Buffers implementing this interface should be compared with case insensitive equals
    364      *
    365      */
    366     public interface CaseInsensitve
    367     {}
    368
    369
    370 }