View Javadoc

    1   /*
    2    *  Licensed to the Apache Software Foundation (ASF) under one
    3    *  or more contributor license agreements.  See the NOTICE file
    4    *  distributed with this work for additional information
    5    *  regarding copyright ownership.  The ASF licenses this file
    6    *  to you under the Apache License, Version 2.0 (the
    7    *  "License"); you may not use this file except in compliance
    8    *  with the License.  You may obtain a copy of the License at
    9    *
    10   *    http://www.apache.org/licenses/LICENSE-2.0
    11   *
    12   *  Unless required by applicable law or agreed to in writing,
    13   *  software distributed under the License is distributed on an
    14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    15   *  KIND, either express or implied.  See the License for the
    16   *  specific language governing permissions and limitations
    17   *  under the License.
    18   *
    19   */
    20  package org.apache.mina.util.byteaccess;
    21
    22  import java.nio.ByteOrder;
    23
    24  import org.apache.mina.core.buffer.IoBuffer;
    25
    26  /**
    27   * Represents a sequence of bytes that can be read or written directly or
    28   * through a cursor.
    29   *
    30   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    31   */
    32  public interface ByteArray extends IoAbsoluteReader, IoAbsoluteWriter {
    33
    34      /**
    35       * @inheritDoc
    36       */
    37      int first();
    38
    39      /**
    40       * @inheritDoc
    41       */
    42      int last();
    43
    44      /**
    45       * @inheritDoc
    46       */
    47      ByteOrder order();
    48
    49      /**
    50       * Set the byte order of the array.
    51       */
    52      void order(ByteOrder order);
    53
    54      /**
    55       * Remove any resources associated with this object. Using the object after
    56       * this method is called may result in undefined behaviour.
    57       */
    58      void free();
    59
    60      /**
    61       * Get the sequence of <code>IoBuffer</code>s that back this array.
    62       * Compared to <code>getSingleIoBuffer()</code>, this method should be
    63       * relatively efficient for all implementations.
    64       */
    65      Iterable<IoBuffer> getIoBuffers();
    66
    67      /**
    68       * Gets a single <code>IoBuffer</code> that backs this array. Some
    69       * implementations may initially have data split across multiple buffers, so
    70       * calling this method may require a new buffer to be allocated and
    71       * populated.
    72       */
    73      IoBuffer getSingleIoBuffer();
    74
    75      /**
    76       * A ByteArray is equal to another ByteArray if they start and end at the
    77       * same index, have the same byte order, and contain the same bytes at each
    78       * index.
    79       */
    80      public boolean equals(Object other);
    81
    82      /**
    83       * @inheritDoc
    84       */
    85      byte get(int index);
    86
    87      /**
    88       * @inheritDoc
    89       */
    90      public void get(int index, IoBuffer bb);
    91
    92      /**
    93       * @inheritDoc
    94       */
    95      int getInt(int index);
    96
    97      /**
    98       * Get a cursor starting at index 0 (which may not be the start of the array).
    99       */
    100     Cursor cursor();
    101
    102     /**
    103      * Get a cursor starting at the given index.
    104      */
    105     Cursor cursor(int index);
    106
    107     /**
    108      * Provides relocatable, relative access to the underlying array. Multiple
    109      * cursors may be used simultaneously, and cursors will stay consistent with
    110      * the underlying array, even across modifications.
    111      *
    112      * Should this be <code>Cloneable</code> to allow cheap mark/position
    113      * emulation?
    114      */
    115     public interface Cursor extends IoRelativeReader, IoRelativeWriter {
    116
    117         /**
    118          * Gets the current index of the cursor.
    119          */
    120         int getIndex();
    121
    122         /**
    123          * Sets the current index of the cursor. No bounds checking will occur
    124          * until an access occurs.
    125          */
    126         void setIndex(int index);
    127
    128         /**
    129          * @inheritDoc
    130          */
    131         int getRemaining();
    132
    133         /**
    134          * @inheritDoc
    135          */
    136         boolean hasRemaining();
    137
    138         /**
    139          * @inheritDoc
    140          */
    141         byte get();
    142
    143         /**
    144          * @inheritDoc
    145          */
    146         void get(IoBuffer bb);
    147
    148         /**
    149          * @inheritDoc
    150          */
    151         int getInt();
    152     }
    153
    154 }