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       * @param order The ByteOrder to use
53       */
54      void order(ByteOrder order);
55  
56      /**
57       * Remove any resources associated with this object. Using the object after
58       * this method is called may result in undefined behaviour.
59       */
60      void free();
61  
62      /**
63       * @return the sequence of <code>IoBuffer</code>s that back this array.
64       * Compared to <code>getSingleIoBuffer()</code>, this method should be
65       * relatively efficient for all implementations.
66       */
67      Iterable<IoBuffer> getIoBuffers();
68  
69      /**
70       * @return a single <code>IoBuffer</code> that backs this array. Some
71       * implementations may initially have data split across multiple buffers, so
72       * calling this method may require a new buffer to be allocated and
73       * populated.
74       */
75      IoBuffer getSingleIoBuffer();
76  
77      /**
78       * A ByteArray is equal to another ByteArray if they start and end at the
79       * same index, have the same byte order, and contain the same bytes at each
80       * index.
81       * 
82       * @param other The ByteArray we want to compare with
83       * @return <tt>true</tt> if both ByteArray are equals
84       */
85      boolean equals(Object other);
86  
87      /**
88       * {@inheritDoc}
89       */
90      byte get(int index);
91  
92      /**
93       * {@inheritDoc}
94       */
95      void get(int index, IoBuffer bb);
96  
97      /**
98       * {@inheritDoc}
99       */
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 }