001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.mina.util.byteaccess;
021
022import java.nio.ByteOrder;
023
024import org.apache.mina.core.buffer.IoBuffer;
025
026/**
027 * Represents a sequence of bytes that can be read or written directly or
028 * through a cursor.
029 * 
030 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
031 */
032public interface ByteArray extends IoAbsoluteReader, IoAbsoluteWriter {
033
034    /**
035     * {@inheritDoc}
036     */
037    int first();
038
039    /**
040     * {@inheritDoc}
041     */
042    int last();
043
044    /**
045     * {@inheritDoc}
046     */
047    ByteOrder order();
048
049    /**
050     * Set the byte order of the array.
051     * 
052     * @param order The ByteOrder to use
053     */
054    void order(ByteOrder order);
055
056    /**
057     * Remove any resources associated with this object. Using the object after
058     * this method is called may result in undefined behaviour.
059     */
060    void free();
061
062    /**
063     * @return the sequence of <code>IoBuffer</code>s that back this array.
064     * Compared to <code>getSingleIoBuffer()</code>, this method should be
065     * relatively efficient for all implementations.
066     */
067    Iterable<IoBuffer> getIoBuffers();
068
069    /**
070     * @return a single <code>IoBuffer</code> that backs this array. Some
071     * implementations may initially have data split across multiple buffers, so
072     * calling this method may require a new buffer to be allocated and
073     * populated.
074     */
075    IoBuffer getSingleIoBuffer();
076
077    /**
078     * A ByteArray is equal to another ByteArray if they start and end at the
079     * same index, have the same byte order, and contain the same bytes at each
080     * index.
081     * 
082     * @param other The ByteArray we want to compare with
083     * @return <tt>true</tt> if both ByteArray are equals
084     */
085    boolean equals(Object other);
086
087    /**
088     * {@inheritDoc}
089     */
090    byte get(int index);
091
092    /**
093     * {@inheritDoc}
094     */
095    void get(int index, IoBuffer bb);
096
097    /**
098     * {@inheritDoc}
099     */
100    int getInt(int index);
101
102    /**
103     * @return a cursor starting at index 0 (which may not be the start of the array).
104     */
105    Cursor cursor();
106
107    /**
108     * @param index The starting point
109     * @return a cursor starting at the given index.
110     */
111    Cursor cursor(int index);
112
113    /**
114     * Provides relocatable, relative access to the underlying array. Multiple
115     * cursors may be used simultaneously, and cursors will stay consistent with
116     * the underlying array, even across modifications.
117     *
118     * Should this be <code>Cloneable</code> to allow cheap mark/position
119     * emulation?
120     */
121    interface Cursor extends IoRelativeReader, IoRelativeWriter {
122
123        /**
124         * @return the current index of the cursor.
125         */
126        int getIndex();
127
128        /**
129         * Sets the current index of the cursor. No bounds checking will occur
130         * until an access occurs.
131         * 
132         * @param index The current index to set
133         */
134        void setIndex(int index);
135
136        /**
137         * {@inheritDoc}
138         */
139        int getRemaining();
140
141        /**
142         * {@inheritDoc}
143         */
144        boolean hasRemaining();
145
146        /**
147         * {@inheritDoc}
148         */
149        byte get();
150
151        /**
152         * {@inheritDoc}
153         */
154        void get(IoBuffer bb);
155
156        /**
157         * {@inheritDoc}
158         */
159        int getInt();
160    }
161}