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