0001: /*
0002: * Licensed to the Apache Software Foundation (ASF) under one or more
0003: * contributor license agreements. See the NOTICE file distributed with
0004: * this work for additional information regarding copyright ownership.
0005: * The ASF licenses this file to You under the Apache License, Version 2.0
0006: * (the "License"); you may not use this file except in compliance with
0007: * the License. You may obtain a copy of the License at
0008: *
0009: * http://www.apache.org/licenses/LICENSE-2.0
0010: *
0011: * Unless required by applicable law or agreed to in writing, software
0012: * distributed under the License is distributed on an "AS IS" BASIS,
0013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014: * See the License for the specific language governing permissions and
0015: * limitations under the License.
0016: */
0017:
0018: package java.nio;
0019:
0020: import org.apache.harmony.luni.platform.Endianness;
0021:
0022: /**
0023: * A buffer of <code>byte</code>s.
0024: * <p>
0025: * A byte buffer can be created in either of the following ways:
0026: * <ul>
0027: * <li>{@link #allocate(int) Allocate} a new byte array and create a buffer
0028: * based on it;</li>
0029: * <li>{@link #allocateDirect(int) Allocate} a memory block and create a direct
0030: * buffer based on it;</li>
0031: * <li>{@link #wrap(byte[]) Wrap} an existing byte array to create a new
0032: * buffer.</li>
0033: * </ul>
0034: * </p>
0035: *
0036: */
0037: public abstract class ByteBuffer extends Buffer implements
0038: Comparable<ByteBuffer> {
0039:
0040: /**
0041: * Creates a byte buffer based on a new allocated byte array.
0042: *
0043: * @param capacity
0044: * The capacity of the new buffer
0045: * @return The created byte buffer
0046: * @throws IllegalArgumentException
0047: * If <code>capacity</code> is less than zero
0048: */
0049: public static ByteBuffer allocate(int capacity) {
0050: if (capacity < 0) {
0051: throw new IllegalArgumentException();
0052: }
0053: return BufferFactory.newByteBuffer(capacity);
0054: }
0055:
0056: /**
0057: * Creates a direct byte buffer based on a new allocated memory block.
0058: *
0059: * @param capacity
0060: * The capacity of the new buffer
0061: * @return The created byte buffer
0062: * @throws IllegalArgumentException
0063: * If <code>capacity</code> is less than zero
0064: */
0065: public static ByteBuffer allocateDirect(int capacity) {
0066: if (capacity < 0) {
0067: throw new IllegalArgumentException();
0068: }
0069: return BufferFactory.newDirectByteBuffer(capacity);
0070: }
0071:
0072: /**
0073: * Creates a new byte buffer by wrapping the given byte array.
0074: * <p>
0075: * Calling this method has the same effect as
0076: * <code>wrap(array, 0, array.length)</code>.
0077: * </p>
0078: *
0079: * @param array
0080: * The byte array which the new buffer will be based on
0081: * @return The created byte buffer
0082: */
0083: public static ByteBuffer wrap(byte[] array) {
0084: return BufferFactory.newByteBuffer(array);
0085: }
0086:
0087: /**
0088: * Creates new a byte buffer by wrapping the given byte array.
0089: * <p>
0090: * The new buffer's position will be <code>start</code>, limit will be
0091: * <code>start + len</code>, capacity will be the length of the array.
0092: * </p>
0093: *
0094: * @param array
0095: * The byte array which the new buffer will be based on
0096: * @param start
0097: * The start index, must be no less than zero and no greater than
0098: * <code>array.length</code>
0099: * @param len
0100: * The length, must be no less than zero and no greater than
0101: * <code>array.length - start</code>
0102: * @return The created byte buffer
0103: * @exception IndexOutOfBoundsException
0104: * If either <code>start</code> or <code>len</code> is
0105: * invalid
0106: */
0107: public static ByteBuffer wrap(byte[] array, int start, int len) {
0108: int length = array.length;
0109: if ((start < 0) || (len < 0)
0110: || ((long) start + (long) len > length)) {
0111: throw new IndexOutOfBoundsException();
0112: }
0113:
0114: ByteBuffer buf = BufferFactory.newByteBuffer(array);
0115: buf.position = start;
0116: buf.limit = start + len;
0117:
0118: return buf;
0119: }
0120:
0121: /**
0122: * The byte order of this buffer, default is <code>BIG_ENDIAN</code>.
0123: */
0124: Endianness order = Endianness.BIG_ENDIAN;
0125:
0126: /**
0127: * Constructs a <code>ByteBuffer</code> with given capacity.
0128: *
0129: * @param capacity
0130: * The capacity of the buffer
0131: */
0132: ByteBuffer(int capacity) {
0133: super (capacity);
0134: }
0135:
0136: /**
0137: * Returns the byte array which this buffer is based on, if there's one.
0138: *
0139: * @return The byte array which this buffer is based on
0140: * @exception ReadOnlyBufferException
0141: * If this buffer is based on a readonly array
0142: * @exception UnsupportedOperationException
0143: * If this buffer is not based on an array
0144: */
0145: public final byte[] array() {
0146: return protectedArray();
0147: }
0148:
0149: /**
0150: * Returns the offset of the byte array which this buffer is based on, if
0151: * there's one.
0152: * <p>
0153: * The offset is the index of the array corresponds to the zero position of
0154: * the buffer.
0155: * </p>
0156: *
0157: * @return The offset of the byte array which this buffer is based on
0158: * @exception ReadOnlyBufferException
0159: * If this buffer is based on a readonly array
0160: * @exception UnsupportedOperationException
0161: * If this buffer is not based on an array
0162: */
0163: public final int arrayOffset() {
0164: return protectedArrayOffset();
0165: }
0166:
0167: /**
0168: * Returns a char buffer which is based on the remaining content of this
0169: * byte buffer.
0170: * <p>
0171: * The new buffer's position is zero, its limit and capacity is the number
0172: * of remaining bytes divided by two, and its mark is not set. The new
0173: * buffer's readonly property and byte order are same as this buffer. The
0174: * new buffer is direct, if this byte buffer is direct.
0175: * </p>
0176: * <p>
0177: * The new buffer shares content with this buffer, which means either
0178: * buffer's change of content will be visible to the other. The two buffer's
0179: * position, limit and mark are independent.
0180: * </p>
0181: *
0182: * @return A char buffer which is based on the content of this byte buffer.
0183: */
0184: public abstract CharBuffer asCharBuffer();
0185:
0186: /**
0187: * Returns a double buffer which is based on the remaining content of this
0188: * byte buffer.
0189: * <p>
0190: * The new buffer's position is zero, its limit and capacity is the number
0191: * of remaining bytes divided by two, and its mark is not set. The new
0192: * buffer's readonly property and byte order are same as this buffer. The
0193: * new buffer is direct, if this byte buffer is direct.
0194: * </p>
0195: * <p>
0196: * The new buffer shares content with this buffer, which means either
0197: * buffer's change of content will be visible to the other. The two buffer's
0198: * position, limit and mark are independent.
0199: * </p>
0200: *
0201: * @return A double buffer which is based on the content of this byte
0202: * buffer.
0203: */
0204: public abstract DoubleBuffer asDoubleBuffer();
0205:
0206: /**
0207: * Returns a float buffer which is based on the remaining content of this
0208: * byte buffer.
0209: * <p>
0210: * The new buffer's position is zero, its limit and capacity is the number
0211: * of remaining bytes divided by two, and its mark is not set. The new
0212: * buffer's readonly property and byte order are same as this buffer. The
0213: * new buffer is direct, if this byte buffer is direct.
0214: * </p>
0215: * <p>
0216: * The new buffer shares content with this buffer, which means either
0217: * buffer's change of content will be visible to the other. The two buffer's
0218: * position, limit and mark are independent.
0219: * </p>
0220: *
0221: * @return A float buffer which is based on the content of this byte buffer.
0222: */
0223: public abstract FloatBuffer asFloatBuffer();
0224:
0225: /**
0226: * Returns a int buffer which is based on the remaining content of this byte
0227: * buffer.
0228: * <p>
0229: * The new buffer's position is zero, its limit and capacity is the number
0230: * of remaining bytes divided by two, and its mark is not set. The new
0231: * buffer's readonly property and byte order are same as this buffer. The
0232: * new buffer is direct, if this byte buffer is direct.
0233: * </p>
0234: * <p>
0235: * The new buffer shares content with this buffer, which means either
0236: * buffer's change of content will be visible to the other. The two buffer's
0237: * position, limit and mark are independent.
0238: * </p>
0239: *
0240: * @return A int buffer which is based on the content of this byte buffer.
0241: */
0242: public abstract IntBuffer asIntBuffer();
0243:
0244: /**
0245: * Returns a long buffer which is based on the remaining content of this
0246: * byte buffer.
0247: * <p>
0248: * The new buffer's position is zero, its limit and capacity is the number
0249: * of remaining bytes divided by two, and its mark is not set. The new
0250: * buffer's readonly property and byte order are same as this buffer. The
0251: * new buffer is direct, if this byte buffer is direct.
0252: * </p>
0253: * <p>
0254: * The new buffer shares content with this buffer, which means either
0255: * buffer's change of content will be visible to the other. The two buffer's
0256: * position, limit and mark are independent.
0257: * </p>
0258: *
0259: * @return A long buffer which is based on the content of this byte buffer.
0260: */
0261: public abstract LongBuffer asLongBuffer();
0262:
0263: /**
0264: * Returns a readonly buffer that shares content with this buffer.
0265: * <p>
0266: * The returned buffer is guaranteed to be a new instance, even if this buffer
0267: * is readonly itself. The new buffer's position, limit, capacity and mark
0268: * are the same as this buffer.
0269: * </p>
0270: * <p>
0271: * The new buffer shares content with this buffer, which means this buffer's
0272: * change of content will be visible to the new buffer. The two buffer's
0273: * position, limit and mark are independent.
0274: * </p>
0275: *
0276: * @return A readonly version of this buffer.
0277: */
0278: public abstract ByteBuffer asReadOnlyBuffer();
0279:
0280: /**
0281: * Returns a short buffer which is based on the remaining content of this
0282: * byte buffer.
0283: * <p>
0284: * The new buffer's position is zero, its limit and capacity is the number
0285: * of remaining bytes divided by two, and its mark is not set. The new
0286: * buffer's readonly property and byte order are same as this buffer. The
0287: * new buffer is direct, if this byte buffer is direct.
0288: * </p>
0289: * <p>
0290: * The new buffer shares content with this buffer, which means either
0291: * buffer's change of content will be visible to the other. The two buffer's
0292: * position, limit and mark are independent.
0293: * </p>
0294: *
0295: * @return A short buffer which is based on the content of this byte buffer.
0296: */
0297: public abstract ShortBuffer asShortBuffer();
0298:
0299: /**
0300: * Compacts this byte buffer.
0301: * <p>
0302: * The remaining <code>byte</code>s will be moved to the head of the
0303: * buffer, staring from position zero. Then the position is set to
0304: * <code>remaining()</code>; the limit is set to capacity; the mark is
0305: * cleared.
0306: * </p>
0307: *
0308: * @return This buffer
0309: * @exception ReadOnlyBufferException
0310: * If no changes may be made to the contents of this buffer
0311: */
0312: public abstract ByteBuffer compact();
0313:
0314: /**
0315: * Compare the remaining <code>byte</code>s of this buffer to another
0316: * byte buffer's remaining <code>byte</code>s.
0317: *
0318: * @param otherBuffer
0319: * Another byte buffer
0320: * @return a negative value if this is less than <code>other</code>; 0 if
0321: * this equals to <code>other</code>; a positive value if this is
0322: * greater than <code>other</code>
0323: * @exception ClassCastException
0324: * If <code>other</code> is not a byte buffer
0325: */
0326: public int compareTo(ByteBuffer otherBuffer) {
0327: int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
0328: : otherBuffer.remaining();
0329: int this Pos = position;
0330: int otherPos = otherBuffer.position;
0331: byte this Byte, otherByte;
0332: while (compareRemaining > 0) {
0333: this Byte = get(this Pos);
0334: otherByte = otherBuffer.get(otherPos);
0335: if (this Byte != otherByte) {
0336: return this Byte < otherByte ? -1 : 1;
0337: }
0338: this Pos++;
0339: otherPos++;
0340: compareRemaining--;
0341: }
0342: return remaining() - otherBuffer.remaining();
0343: }
0344:
0345: /**
0346: * Returns a duplicated buffer that shares content with this buffer.
0347: * <p>
0348: * The duplicated buffer's position, limit, capacity and mark are the same
0349: * as this buffer. The duplicated buffer's readonly property and byte order
0350: * are same as this buffer too.
0351: * </p>
0352: * <p>
0353: * The new buffer shares content with this buffer, which means either
0354: * buffer's change of content will be visible to the other. The two buffer's
0355: * position, limit and mark are independent.
0356: * </p>
0357: *
0358: * @return A duplicated buffer that shares content with this buffer.
0359: */
0360: public abstract ByteBuffer duplicate();
0361:
0362: /**
0363: * Tests whether this byte buffer equals to another object.
0364: * <p>
0365: * If <code>other</code> is not a byte buffer, then false is returned.
0366: * </p>
0367: * <p>
0368: * Two byte buffers are equals if, and only if, their remaining
0369: * <code>byte</code>s are exactly the same. Position, limit, capacity and
0370: * mark are not considered.
0371: * </p>
0372: *
0373: * @param other
0374: * the object to compare against
0375: * @return Whether this byte buffer equals to another object.
0376: */
0377: @Override
0378: public boolean equals(Object other) {
0379: if (!(other instanceof ByteBuffer)) {
0380: return false;
0381: }
0382: ByteBuffer otherBuffer = (ByteBuffer) other;
0383:
0384: if (remaining() != otherBuffer.remaining()) {
0385: return false;
0386: }
0387:
0388: int myPosition = position;
0389: int otherPosition = otherBuffer.position;
0390: boolean equalSoFar = true;
0391: while (equalSoFar && (myPosition < limit)) {
0392: equalSoFar = get(myPosition++) == otherBuffer
0393: .get(otherPosition++);
0394: }
0395:
0396: return equalSoFar;
0397: }
0398:
0399: /**
0400: * Returns the byte at the current position and increase the position by 1.
0401: *
0402: * @return The byte at the current position.
0403: * @exception BufferUnderflowException
0404: * If the position is equal or greater than limit
0405: */
0406: public abstract byte get();
0407:
0408: /**
0409: * Reads <code>byte</code>s from the current position into the specified
0410: * byte array and increase the position by the number of <code>byte</code>s
0411: * read.
0412: * <p>
0413: * Calling this method has the same effect as
0414: * <code>get(dest, 0, dest.length)</code>.
0415: * </p>
0416: *
0417: * @param dest
0418: * The destination byte array
0419: * @return This buffer
0420: * @exception BufferUnderflowException
0421: * if <code>dest.length</code> is greater than
0422: * <code>remaining()</code>
0423: */
0424: public ByteBuffer get(byte[] dest) {
0425: return get(dest, 0, dest.length);
0426: }
0427:
0428: /**
0429: * Reads <code>byte</code>s from the current position into the specified
0430: * byte array, starting from the specified offset, and increase the position
0431: * by the number of <code>byte</code>s read.
0432: *
0433: * @param dest
0434: * The target byte array
0435: * @param off
0436: * The offset of the byte array, must be no less than zero and no
0437: * greater than <code>dest.length</code>
0438: * @param len
0439: * The number of <code>byte</code>s to read, must be no less
0440: * than zero and no greater than <code>dest.length - off</code>
0441: * @return This buffer
0442: * @exception IndexOutOfBoundsException
0443: * If either <code>off</code> or <code>len</code> is
0444: * invalid
0445: * @exception BufferUnderflowException
0446: * If <code>len</code> is greater than
0447: * <code>remaining()</code>
0448: */
0449: public ByteBuffer get(byte[] dest, int off, int len) {
0450: int length = dest.length;
0451: if ((off < 0) || (len < 0)
0452: || ((long) off + (long) len > length)) {
0453: throw new IndexOutOfBoundsException();
0454: }
0455:
0456: if (len > remaining()) {
0457: throw new BufferUnderflowException();
0458: }
0459: for (int i = off; i < off + len; i++) {
0460: dest[i] = get();
0461: }
0462: return this ;
0463: }
0464:
0465: /**
0466: * Returns a byte at the specified index, and the position is not changed.
0467: *
0468: * @param index
0469: * The index, must be no less than zero and less than limit
0470: * @return A byte at the specified index.
0471: * @exception IndexOutOfBoundsException
0472: * If index is invalid
0473: */
0474: public abstract byte get(int index);
0475:
0476: /**
0477: * Returns the char at the current position and increase the position by 2.
0478: * <p>
0479: * The 2 bytes start from the current position are composed into a char
0480: * according to current byte order and returned. The position increases by
0481: * 2.
0482: * </p>
0483: *
0484: * @return The char at the current position.
0485: * @exception BufferUnderflowException
0486: * If the position is greater than <code>limit - 2</code>
0487: */
0488: public abstract char getChar();
0489:
0490: /**
0491: * Returns the char at the specified index.
0492: * <p>
0493: * The 2 bytes start from the specified index are composed into a char
0494: * according to current byte order and returned. The position is not
0495: * changed.
0496: * </p>
0497: *
0498: * @param index
0499: * The index, must be no less than zero and equal or less than
0500: * <code>limit - 2</code>
0501: * @return The char at the specified index.
0502: * @exception IndexOutOfBoundsException
0503: * If <code>index</code> is invalid
0504: */
0505: public abstract char getChar(int index);
0506:
0507: /**
0508: * Returns the double at the current position and increase the position by
0509: * 8.
0510: * <p>
0511: * The 8 bytes start from the current position are composed into a double
0512: * according to current byte order and returned. The position increases by
0513: * 8.
0514: * </p>
0515: *
0516: * @return The double at the current position.
0517: * @exception BufferUnderflowException
0518: * If the position is greater than <code>limit - 8</code>
0519: */
0520: public abstract double getDouble();
0521:
0522: /**
0523: * Returns the double at the specified index.
0524: * <p>
0525: * The 8 bytes start from the specified index are composed into a double
0526: * according to current byte order and returned. The position is not
0527: * changed.
0528: * </p>
0529: *
0530: * @param index
0531: * The index, must be no less than zero and equal or less than
0532: * <code>limit - 8</code>
0533: * @return The double at the specified index.
0534: * @exception IndexOutOfBoundsException
0535: * If <code>index</code> is invalid
0536: */
0537: public abstract double getDouble(int index);
0538:
0539: /**
0540: * Returns the float at the current position and increase the position by 4.
0541: * <p>
0542: * The 4 bytes start from the current position are composed into a float
0543: * according to current byte order and returned. The position increases by
0544: * 4.
0545: * </p>
0546: *
0547: * @return The float at the current position.
0548: * @exception BufferUnderflowException
0549: * If the position is greater than <code>limit - 4</code>
0550: */
0551: public abstract float getFloat();
0552:
0553: /**
0554: * Returns the float at the specified index.
0555: * <p>
0556: * The 4 bytes start from the specified index are composed into a float
0557: * according to current byte order and returned. The position is not
0558: * changed.
0559: * </p>
0560: *
0561: * @param index
0562: * The index, must be no less than zero and equal or less than
0563: * <code>limit - 4</code>
0564: * @return The float at the specified index.
0565: * @exception IndexOutOfBoundsException
0566: * If <code>index</code> is invalid
0567: */
0568: public abstract float getFloat(int index);
0569:
0570: /**
0571: * Returns the int at the current position and increase the position by 4.
0572: * <p>
0573: * The 4 bytes start from the current position are composed into a int
0574: * according to current byte order and returned. The position increases by
0575: * 4.
0576: * </p>
0577: *
0578: * @return The int at the current position.
0579: * @exception BufferUnderflowException
0580: * If the position is greater than <code>limit - 4</code>
0581: */
0582: public abstract int getInt();
0583:
0584: /**
0585: * Returns the int at the specified index.
0586: * <p>
0587: * The 4 bytes start from the specified index are composed into a int
0588: * according to current byte order and returned. The position is not
0589: * changed.
0590: * </p>
0591: *
0592: * @param index
0593: * The index, must be no less than zero and equal or less than
0594: * <code>limit - 4</code>
0595: * @return The int at the specified index.
0596: * @exception IndexOutOfBoundsException
0597: * If <code>index</code> is invalid
0598: */
0599: public abstract int getInt(int index);
0600:
0601: /**
0602: * Returns the long at the current position and increase the position by 8.
0603: * <p>
0604: * The 8 bytes start from the current position are composed into a long
0605: * according to current byte order and returned. The position increases by
0606: * 8.
0607: * </p>
0608: *
0609: * @return The long at the current position.
0610: * @exception BufferUnderflowException
0611: * If the position is greater than <code>limit - 8</code>
0612: */
0613: public abstract long getLong();
0614:
0615: /**
0616: * Returns the long at the specified index.
0617: * <p>
0618: * The 8 bytes start from the specified index are composed into a long
0619: * according to current byte order and returned. The position is not
0620: * changed.
0621: * </p>
0622: *
0623: * @param index
0624: * The index, must be no less than zero and equal or less than
0625: * <code>limit - 8</code>
0626: * @return The long at the specified index.
0627: * @exception IndexOutOfBoundsException
0628: * If <code>index</code> is invalid
0629: */
0630: public abstract long getLong(int index);
0631:
0632: /**
0633: * Returns the short at the current position and increase the position by 2.
0634: * <p>
0635: * The 2 bytes start from the current position are composed into a short
0636: * according to current byte order and returned. The position increases by
0637: * 2.
0638: * </p>
0639: *
0640: * @return The short at the current position.
0641: * @exception BufferUnderflowException
0642: * If the position is greater than <code>limit - 2</code>
0643: */
0644: public abstract short getShort();
0645:
0646: /**
0647: * Returns the short at the specified index.
0648: * <p>
0649: * The 2 bytes start from the specified index are composed into a short
0650: * according to current byte order and returned. The position is not
0651: * changed.
0652: * </p>
0653: *
0654: * @param index
0655: * The index, must be no less than zero and equal or less than
0656: * <code>limit - 2</code>
0657: * @return The short at the specified index.
0658: * @exception IndexOutOfBoundsException
0659: * If <code>index</code> is invalid
0660: */
0661: public abstract short getShort(int index);
0662:
0663: /**
0664: * Returns whether this buffer is based on a byte array and is read/write.
0665: * <p>
0666: * If this buffer is readonly, then false is returned.
0667: * </p>
0668: *
0669: * @return Whether this buffer is based on a byte array and is read/write.
0670: */
0671: public final boolean hasArray() {
0672: return protectedHasArray();
0673: }
0674:
0675: /**
0676: * Hash code is calculated from the remaining <code>byte</code>s.
0677: * <p>
0678: * Position, limit, capacity and mark don't affect the hash code.
0679: * </p>
0680: *
0681: * @return The hash code calculated from the remaining <code>byte</code>s.
0682: */
0683: @Override
0684: public int hashCode() {
0685: int myPosition = position;
0686: int hash = 0;
0687: while (myPosition < limit) {
0688: hash = hash + get(myPosition++);
0689: }
0690: return hash;
0691: }
0692:
0693: /**
0694: * Returns true if this buffer is direct.
0695: * <p>
0696: * A byte buffer is direct, if it is based on a byte buffer and the byte
0697: * buffer is direct.
0698: * </p>
0699: *
0700: * @return True if this buffer is direct.
0701: */
0702: public abstract boolean isDirect();
0703:
0704: /**
0705: * Returns the byte order used by this buffer when converting
0706: * <code>byte</code>s from/to other primitive types.
0707: * <p>
0708: * The default byte order of byte buffer is always BIG_ENDIAN.
0709: * </p>
0710: *
0711: * @return The byte order used by this buffer when converting
0712: * <code>byte</code>s from/to other primitive types.
0713: */
0714: public final ByteOrder order() {
0715: return order == Endianness.BIG_ENDIAN ? ByteOrder.BIG_ENDIAN
0716: : ByteOrder.LITTLE_ENDIAN;
0717: }
0718:
0719: /**
0720: * Sets the byte order of this buffer.
0721: *
0722: * @param byteOrder
0723: * The byte order to set. If <code>null</code> then the order
0724: * will be {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}.
0725: * @return This buffer
0726: * @see ByteOrder
0727: */
0728: public final ByteBuffer order(ByteOrder byteOrder) {
0729: return orderImpl(byteOrder);
0730: }
0731:
0732: ByteBuffer orderImpl(ByteOrder byteOrder) {
0733: order = byteOrder == ByteOrder.BIG_ENDIAN ? Endianness.BIG_ENDIAN
0734: : Endianness.LITTLE_ENDIAN;
0735: return this ;
0736: }
0737:
0738: /**
0739: * Child class implements this method to realize <code>array()</code>.
0740: *
0741: * @return see <code>array()</code>
0742: */
0743: abstract byte[] protectedArray();
0744:
0745: /**
0746: * Child class implements this method to realize <code>arrayOffset()</code>.
0747: *
0748: * @return see <code>arrayOffset()</code>
0749: */
0750: abstract int protectedArrayOffset();
0751:
0752: /**
0753: * Child class implements this method to realize <code>hasArray()</code>.
0754: *
0755: * @return see <code>hasArray()</code>
0756: */
0757: abstract boolean protectedHasArray();
0758:
0759: /**
0760: * Writes the given byte to the current position and increase the position
0761: * by 1.
0762: *
0763: * @param b
0764: * The byte to write
0765: * @return This buffer
0766: * @exception BufferOverflowException
0767: * If position is equal or greater than limit
0768: * @exception ReadOnlyBufferException
0769: * If no changes may be made to the contents of this buffer
0770: */
0771: public abstract ByteBuffer put(byte b);
0772:
0773: /**
0774: * Writes <code>byte</code>s in the given byte array to the current
0775: * position and increase the position by the number of <code>byte</code>s
0776: * written.
0777: * <p>
0778: * Calling this method has the same effect as
0779: * <code>put(src, 0, src.length)</code>.
0780: * </p>
0781: *
0782: * @param src
0783: * The source byte array
0784: * @return This buffer
0785: * @exception BufferOverflowException
0786: * If <code>remaining()</code> is less than
0787: * <code>src.length</code>
0788: * @exception ReadOnlyBufferException
0789: * If no changes may be made to the contents of this buffer
0790: */
0791: public final ByteBuffer put(byte[] src) {
0792: return put(src, 0, src.length);
0793: }
0794:
0795: /**
0796: * Writes <code>byte</code>s in the given byte array, starting from the
0797: * specified offset, to the current position and increase the position by
0798: * the number of <code>byte</code>s written.
0799: *
0800: * @param src
0801: * The source byte array
0802: * @param off
0803: * The offset of byte array, must be no less than zero and no
0804: * greater than <code>src.length</code>
0805: * @param len
0806: * The number of <code>byte</code>s to write, must be no less
0807: * than zero and no greater than <code>src.length - off</code>
0808: * @return This buffer
0809: * @exception BufferOverflowException
0810: * If <code>remaining()</code> is less than
0811: * <code>len</code>
0812: * @exception IndexOutOfBoundsException
0813: * If either <code>off</code> or <code>len</code> is
0814: * invalid
0815: * @exception ReadOnlyBufferException
0816: * If no changes may be made to the contents of this buffer
0817: */
0818: public ByteBuffer put(byte[] src, int off, int len) {
0819: int length = src.length;
0820: if ((off < 0) || (len < 0)
0821: || ((long) off + (long) len > length)) {
0822: throw new IndexOutOfBoundsException();
0823: }
0824:
0825: if (len > remaining()) {
0826: throw new BufferOverflowException();
0827: }
0828: for (int i = off; i < off + len; i++) {
0829: put(src[i]);
0830: }
0831: return this ;
0832: }
0833:
0834: /**
0835: * Writes all the remaining <code>byte</code>s of the <code>src</code>
0836: * byte buffer to this buffer's current position, and increase both buffers'
0837: * position by the number of <code>byte</code>s copied.
0838: *
0839: * @param src
0840: * The source byte buffer
0841: * @return This buffer
0842: * @exception BufferOverflowException
0843: * If <code>src.remaining()</code> is greater than this
0844: * buffer's <code>remaining()</code>
0845: * @exception IllegalArgumentException
0846: * If <code>src</code> is this buffer
0847: * @exception ReadOnlyBufferException
0848: * If no changes may be made to the contents of this buffer
0849: */
0850: public ByteBuffer put(ByteBuffer src) {
0851: if (src == this ) {
0852: throw new IllegalArgumentException();
0853: }
0854: if (src.remaining() > remaining()) {
0855: throw new BufferOverflowException();
0856: }
0857: byte[] contents = new byte[src.remaining()];
0858: src.get(contents);
0859: put(contents);
0860: return this ;
0861: }
0862:
0863: /**
0864: * Write a byte to the specified index of this buffer and the position is
0865: * not changed.
0866: *
0867: * @param index
0868: * The index, must be no less than zero and less than the limit
0869: * @param b
0870: * The byte to write
0871: * @return This buffer
0872: * @exception IndexOutOfBoundsException
0873: * If <code>index</code> is invalid
0874: * @exception ReadOnlyBufferException
0875: * If no changes may be made to the contents of this buffer
0876: */
0877: public abstract ByteBuffer put(int index, byte b);
0878:
0879: /**
0880: * Writes the given char to the current position and increase the position
0881: * by 2.
0882: * <p>
0883: * The char is converted to bytes using the current byte order.
0884: * </p>
0885: *
0886: * @param value
0887: * The char to write
0888: * @return This buffer
0889: * @exception BufferOverflowException
0890: * If position is greater than <code>limit - 2</code>
0891: * @exception ReadOnlyBufferException
0892: * If no changes may be made to the contents of this buffer
0893: */
0894: public abstract ByteBuffer putChar(char value);
0895:
0896: /**
0897: * Write a char to the specified index of this buffer.
0898: * <p>
0899: * The char is converted to bytes using the current byte order. The position
0900: * is not changed.
0901: * </p>
0902: *
0903: * @param index
0904: * The index, must be no less than zero and equal or less than
0905: * <code>limit - 2</code>
0906: * @param value
0907: * The char to write
0908: * @return This buffer
0909: * @exception IndexOutOfBoundsException
0910: * If <code>index</code> is invalid
0911: * @exception ReadOnlyBufferException
0912: * If no changes may be made to the contents of this buffer
0913: */
0914: public abstract ByteBuffer putChar(int index, char value);
0915:
0916: /**
0917: * Writes the given double to the current position and increase the position
0918: * by 8.
0919: * <p>
0920: * The double is converted to bytes using the current byte order.
0921: * </p>
0922: *
0923: * @param value
0924: * The double to write
0925: * @return This buffer
0926: * @exception BufferOverflowException
0927: * If position is greater than <code>limit - 8</code>
0928: * @exception ReadOnlyBufferException
0929: * If no changes may be made to the contents of this buffer
0930: */
0931: public abstract ByteBuffer putDouble(double value);
0932:
0933: /**
0934: * Write a double to the specified index of this buffer.
0935: * <p>
0936: * The double is converted to bytes using the current byte order. The
0937: * position is not changed.
0938: * </p>
0939: *
0940: * @param index
0941: * The index, must be no less than zero and equal or less than
0942: * <code>limit - 8</code>
0943: * @param value
0944: * The double to write
0945: * @return This buffer
0946: * @exception IndexOutOfBoundsException
0947: * If <code>index</code> is invalid
0948: * @exception ReadOnlyBufferException
0949: * If no changes may be made to the contents of this buffer
0950: */
0951: public abstract ByteBuffer putDouble(int index, double value);
0952:
0953: /**
0954: * Writes the given float to the current position and increase the position
0955: * by 4.
0956: * <p>
0957: * The float is converted to bytes using the current byte order.
0958: * </p>
0959: *
0960: * @param value
0961: * The float to write
0962: * @return This buffer
0963: * @exception BufferOverflowException
0964: * If position is greater than <code>limit - 4</code>
0965: * @exception ReadOnlyBufferException
0966: * If no changes may be made to the contents of this buffer
0967: */
0968: public abstract ByteBuffer putFloat(float value);
0969:
0970: /**
0971: * Write a float to the specified index of this buffer.
0972: * <p>
0973: * The float is converted to bytes using the current byte order. The
0974: * position is not changed.
0975: * </p>
0976: *
0977: * @param index
0978: * The index, must be no less than zero and equal or less than
0979: * <code>limit - 4</code>
0980: * @param value
0981: * The float to write
0982: * @return This buffer
0983: * @exception IndexOutOfBoundsException
0984: * If <code>index</code> is invalid
0985: * @exception ReadOnlyBufferException
0986: * If no changes may be made to the contents of this buffer
0987: */
0988: public abstract ByteBuffer putFloat(int index, float value);
0989:
0990: /**
0991: * Writes the given int to the current position and increase the position by
0992: * 4.
0993: * <p>
0994: * The int is converted to bytes using the current byte order.
0995: * </p>
0996: *
0997: * @param value
0998: * The int to write
0999: * @return This buffer
1000: * @exception BufferOverflowException
1001: * If position is greater than <code>limit - 4</code>
1002: * @exception ReadOnlyBufferException
1003: * If no changes may be made to the contents of this buffer
1004: */
1005: public abstract ByteBuffer putInt(int value);
1006:
1007: /**
1008: * Write a int to the specified index of this buffer.
1009: * <p>
1010: * The int is converted to bytes using the current byte order. The position
1011: * is not changed.
1012: * </p>
1013: *
1014: * @param index
1015: * The index, must be no less than zero and equal or less than
1016: * <code>limit - 4</code>
1017: * @param value
1018: * The int to write
1019: * @return This buffer
1020: * @exception IndexOutOfBoundsException
1021: * If <code>index</code> is invalid
1022: * @exception ReadOnlyBufferException
1023: * If no changes may be made to the contents of this buffer
1024: */
1025: public abstract ByteBuffer putInt(int index, int value);
1026:
1027: /**
1028: * Writes the given long to the current position and increase the position
1029: * by 8.
1030: * <p>
1031: * The long is converted to bytes using the current byte order.
1032: * </p>
1033: *
1034: * @param value
1035: * The long to write
1036: * @return This buffer
1037: * @exception BufferOverflowException
1038: * If position is greater than <code>limit - 8</code>
1039: * @exception ReadOnlyBufferException
1040: * If no changes may be made to the contents of this buffer
1041: */
1042: public abstract ByteBuffer putLong(long value);
1043:
1044: /**
1045: * Write a long to the specified index of this buffer.
1046: * <p>
1047: * The long is converted to bytes using the current byte order. The position
1048: * is not changed.
1049: * </p>
1050: *
1051: * @param index
1052: * The index, must be no less than zero and equal or less than
1053: * <code>limit - 8</code>
1054: * @param value
1055: * The long to write
1056: * @return This buffer
1057: * @exception IndexOutOfBoundsException
1058: * If <code>index</code> is invalid
1059: * @exception ReadOnlyBufferException
1060: * If no changes may be made to the contents of this buffer
1061: */
1062: public abstract ByteBuffer putLong(int index, long value);
1063:
1064: /**
1065: * Writes the given short to the current position and increase the position
1066: * by 2.
1067: * <p>
1068: * The short is converted to bytes using the current byte order.
1069: * </p>
1070: *
1071: * @param value
1072: * The short to write
1073: * @return This buffer
1074: * @exception BufferOverflowException
1075: * If position is greater than <code>limit - 2</code>
1076: * @exception ReadOnlyBufferException
1077: * If no changes may be made to the contents of this buffer
1078: */
1079: public abstract ByteBuffer putShort(short value);
1080:
1081: /**
1082: * Write a short to the specified index of this buffer.
1083: * <p>
1084: * The short is converted to bytes using the current byte order. The
1085: * position is not changed.
1086: * </p>
1087: *
1088: * @param index
1089: * The index, must be no less than zero and equal or less than
1090: * <code>limit - 2</code>
1091: * @param value
1092: * The short to write
1093: * @return This buffer
1094: * @exception IndexOutOfBoundsException
1095: * If <code>index</code> is invalid
1096: * @exception ReadOnlyBufferException
1097: * If no changes may be made to the contents of this buffer
1098: */
1099: public abstract ByteBuffer putShort(int index, short value);
1100:
1101: /**
1102: * Returns a sliced buffer that shares content with this buffer.
1103: * <p>
1104: * The sliced buffer's capacity will be this buffer's
1105: * <code>remaining()</code>, and its zero position will correspond to
1106: * this buffer's current position. The new buffer's position will be 0,
1107: * limit will be its capacity, and its mark is unset. The new buffer's
1108: * readonly property and byte order are same as this buffer.
1109: * </p>
1110: * <p>
1111: * The new buffer shares content with this buffer, which means either
1112: * buffer's change of content will be visible to the other. The two buffer's
1113: * position, limit and mark are independent.
1114: * </p>
1115: *
1116: * @return A sliced buffer that shares content with this buffer.
1117: */
1118: public abstract ByteBuffer slice();
1119:
1120: /**
1121: * Returns a string represents the state of this byte buffer.
1122: *
1123: * @return A string represents the state of this byte buffer.
1124: */
1125: @Override
1126: public String toString() {
1127: StringBuffer buf = new StringBuffer();
1128: buf.append(getClass().getName());
1129: buf.append(", status: capacity="); //$NON-NLS-1$
1130: buf.append(capacity());
1131: buf.append(" position="); //$NON-NLS-1$
1132: buf.append(position());
1133: buf.append(" limit="); //$NON-NLS-1$
1134: buf.append(limit());
1135: return buf.toString();
1136: }
1137: }
|