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