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