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 @Override
38 int first();
39
40 /**
41 * {@inheritDoc}
42 */
43 @Override
44 int last();
45
46 /**
47 * {@inheritDoc}
48 */
49 @Override
50 ByteOrder order();
51
52 /**
53 * Set the byte order of the array.
54 *
55 * @param order The ByteOrder to use
56 */
57 void order(ByteOrder order);
58
59 /**
60 * Remove any resources associated with this object. Using the object after
61 * this method is called may result in undefined behaviour.
62 */
63 void free();
64
65 /**
66 * @return the sequence of <code>IoBuffer</code>s that back this array.
67 * Compared to <code>getSingleIoBuffer()</code>, this method should be
68 * relatively efficient for all implementations.
69 */
70 Iterable<IoBuffer> getIoBuffers();
71
72 /**
73 * @return a single <code>IoBuffer</code> that backs this array. Some
74 * implementations may initially have data split across multiple buffers, so
75 * calling this method may require a new buffer to be allocated and
76 * populated.
77 */
78 IoBuffer getSingleIoBuffer();
79
80 /**
81 * A ByteArray is equal to another ByteArray if they start and end at the
82 * same index, have the same byte order, and contain the same bytes at each
83 * index.
84 *
85 * @param other The ByteArray we want to compare with
86 * @return <tt>true</tt> if both ByteArray are equals
87 */
88 @Override
89 boolean equals(Object other);
90
91 /**
92 * {@inheritDoc}
93 */
94 @Override
95 byte get(int index);
96
97 /**
98 * {@inheritDoc}
99 */
100 @Override
101 void get(int index, IoBuffer bb);
102
103 /**
104 * {@inheritDoc}
105 */
106 @Override
107 int getInt(int index);
108
109 /**
110 * @return a cursor starting at index 0 (which may not be the start of the array).
111 */
112 Cursor cursor();
113
114 /**
115 * @param index The starting point
116 * @return a cursor starting at the given index.
117 */
118 Cursor cursor(int index);
119
120 /**
121 * Provides relocatable, relative access to the underlying array. Multiple
122 * cursors may be used simultaneously, and cursors will stay consistent with
123 * the underlying array, even across modifications.
124 *
125 * Should this be <code>Cloneable</code> to allow cheap mark/position
126 * emulation?
127 */
128 interface Cursor extends IoRelativeReader, IoRelativeWriter {
129
130 /**
131 * @return the current index of the cursor.
132 */
133 int getIndex();
134
135 /**
136 * Sets the current index of the cursor. No bounds checking will occur
137 * until an access occurs.
138 *
139 * @param index The current index to set
140 */
141 void setIndex(int index);
142
143 /**
144 * {@inheritDoc}
145 */
146 @Override
147 int getRemaining();
148
149 /**
150 * {@inheritDoc}
151 */
152 @Override
153 boolean hasRemaining();
154
155 /**
156 * {@inheritDoc}
157 */
158 @Override
159 byte get();
160
161 /**
162 * {@inheritDoc}
163 */
164 @Override
165 void get(IoBuffer bb);
166
167 /**
168 * {@inheritDoc}
169 */
170 @Override
171 int getInt();
172 }
173 }