001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.mina.util.byteaccess; 021 022import java.nio.ByteOrder; 023 024import org.apache.mina.core.buffer.IoBuffer; 025 026/** 027 * Represents a sequence of bytes that can be read or written directly or 028 * through a cursor. 029 * 030 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 031 */ 032public interface ByteArray extends IoAbsoluteReader, IoAbsoluteWriter { 033 034 /** 035 * {@inheritDoc} 036 */ 037 int first(); 038 039 /** 040 * {@inheritDoc} 041 */ 042 int last(); 043 044 /** 045 * {@inheritDoc} 046 */ 047 ByteOrder order(); 048 049 /** 050 * Set the byte order of the array. 051 * 052 * @param order The ByteOrder to use 053 */ 054 void order(ByteOrder order); 055 056 /** 057 * Remove any resources associated with this object. Using the object after 058 * this method is called may result in undefined behaviour. 059 */ 060 void free(); 061 062 /** 063 * @return the sequence of <code>IoBuffer</code>s that back this array. 064 * Compared to <code>getSingleIoBuffer()</code>, this method should be 065 * relatively efficient for all implementations. 066 */ 067 Iterable<IoBuffer> getIoBuffers(); 068 069 /** 070 * @return a single <code>IoBuffer</code> that backs this array. Some 071 * implementations may initially have data split across multiple buffers, so 072 * calling this method may require a new buffer to be allocated and 073 * populated. 074 */ 075 IoBuffer getSingleIoBuffer(); 076 077 /** 078 * A ByteArray is equal to another ByteArray if they start and end at the 079 * same index, have the same byte order, and contain the same bytes at each 080 * index. 081 * 082 * @param other The ByteArray we want to compare with 083 * @return <tt>true</tt> if both ByteArray are equals 084 */ 085 boolean equals(Object other); 086 087 /** 088 * {@inheritDoc} 089 */ 090 byte get(int index); 091 092 /** 093 * {@inheritDoc} 094 */ 095 void get(int index, IoBuffer bb); 096 097 /** 098 * {@inheritDoc} 099 */ 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}