annotate src/java.base/share/classes/java/nio/X-Buffer-bin.java.template @ 12418:950f14c10fc9

8065570: (bf spec) ByteBuffer.slice() should make it clear that the initial order is BIG_ENDIAN Summary: Refine documentation of allocate*(), wrap(), slice(), duplicate(), asReadOnlyBuffer(), and as{Type}Buffer() to explcitly state the byte order of the created buffer. Reviewed-by: alanb
author bpb
date Wed, 15 Jul 2015 10:43:07 -0700
parents f08705540498
children 6f3a2d6e646b
rev   line source
duke@0 1 /*
bpb@12418 2 * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
duke@0 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@0 4 *
duke@0 5 * This code is free software; you can redistribute it and/or modify it
duke@0 6 * under the terms of the GNU General Public License version 2 only, as
ohair@2362 7 * published by the Free Software Foundation. Oracle designates this
duke@0 8 * particular file as subject to the "Classpath" exception as provided
ohair@2362 9 * by Oracle in the LICENSE file that accompanied this code.
duke@0 10 *
duke@0 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@0 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@0 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@0 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@0 15 * accompanied this code).
duke@0 16 *
duke@0 17 * You should have received a copy of the GNU General Public License version
duke@0 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@0 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@0 20 *
ohair@2362 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@2362 22 * or visit www.oracle.com if you need additional information or have any
ohair@2362 23 * questions.
duke@0 24 */
duke@0 25
duke@0 26 #warn This file is preprocessed before being compiled
duke@0 27
duke@0 28 class XXX {
duke@0 29
duke@0 30 #begin
duke@0 31
duke@0 32 /**
duke@0 33 * Relative <i>get</i> method for reading $a$ $type$ value.
duke@0 34 *
duke@0 35 * <p> Reads the next $nbytes$ bytes at this buffer's current position,
duke@0 36 * composing them into $a$ $type$ value according to the current byte order,
duke@0 37 * and then increments the position by $nbytes$. </p>
duke@0 38 *
duke@0 39 * @return The $type$ value at the buffer's current position
duke@0 40 *
duke@0 41 * @throws BufferUnderflowException
duke@0 42 * If there are fewer than $nbytes$ bytes
duke@0 43 * remaining in this buffer
duke@0 44 */
duke@0 45 public abstract $type$ get$Type$();
duke@0 46
duke@0 47 /**
duke@0 48 * Relative <i>put</i> method for writing $a$ $type$
duke@0 49 * value&nbsp;&nbsp;<i>(optional operation)</i>.
duke@0 50 *
duke@0 51 * <p> Writes $nbytes$ bytes containing the given $type$ value, in the
duke@0 52 * current byte order, into this buffer at the current position, and then
duke@0 53 * increments the position by $nbytes$. </p>
duke@0 54 *
duke@0 55 * @param value
duke@0 56 * The $type$ value to be written
duke@0 57 *
duke@0 58 * @return This buffer
duke@0 59 *
duke@0 60 * @throws BufferOverflowException
duke@0 61 * If there are fewer than $nbytes$ bytes
duke@0 62 * remaining in this buffer
duke@0 63 *
duke@0 64 * @throws ReadOnlyBufferException
duke@0 65 * If this buffer is read-only
duke@0 66 */
duke@0 67 public abstract ByteBuffer put$Type$($type$ value);
duke@0 68
duke@0 69 /**
duke@0 70 * Absolute <i>get</i> method for reading $a$ $type$ value.
duke@0 71 *
duke@0 72 * <p> Reads $nbytes$ bytes at the given index, composing them into a
duke@0 73 * $type$ value according to the current byte order. </p>
duke@0 74 *
duke@0 75 * @param index
duke@0 76 * The index from which the bytes will be read
duke@0 77 *
duke@0 78 * @return The $type$ value at the given index
duke@0 79 *
duke@0 80 * @throws IndexOutOfBoundsException
duke@0 81 * If <tt>index</tt> is negative
duke@0 82 * or not smaller than the buffer's limit,
duke@0 83 * minus $nbytesButOne$
duke@0 84 */
duke@0 85 public abstract $type$ get$Type$(int index);
duke@0 86
duke@0 87 /**
duke@0 88 * Absolute <i>put</i> method for writing $a$ $type$
duke@0 89 * value&nbsp;&nbsp;<i>(optional operation)</i>.
duke@0 90 *
duke@0 91 * <p> Writes $nbytes$ bytes containing the given $type$ value, in the
duke@0 92 * current byte order, into this buffer at the given index. </p>
duke@0 93 *
duke@0 94 * @param index
duke@0 95 * The index at which the bytes will be written
duke@0 96 *
duke@0 97 * @param value
duke@0 98 * The $type$ value to be written
duke@0 99 *
duke@0 100 * @return This buffer
duke@0 101 *
duke@0 102 * @throws IndexOutOfBoundsException
duke@0 103 * If <tt>index</tt> is negative
duke@0 104 * or not smaller than the buffer's limit,
duke@0 105 * minus $nbytesButOne$
duke@0 106 *
duke@0 107 * @throws ReadOnlyBufferException
duke@0 108 * If this buffer is read-only
duke@0 109 */
duke@0 110 public abstract ByteBuffer put$Type$(int index, $type$ value);
duke@0 111
duke@0 112 /**
duke@0 113 * Creates a view of this byte buffer as $a$ $type$ buffer.
duke@0 114 *
duke@0 115 * <p> The content of the new buffer will start at this buffer's current
duke@0 116 * position. Changes to this buffer's content will be visible in the new
duke@0 117 * buffer, and vice versa; the two buffers' position, limit, and mark
duke@0 118 * values will be independent.
duke@0 119 *
duke@0 120 * <p> The new buffer's position will be zero, its capacity and its limit
duke@0 121 * will be the number of bytes remaining in this buffer divided by
bpb@12418 122 * $nbytes$, its mark will be undefined, and its byte order will be that
bpb@12418 123 * of the byte buffer at the moment the view is created. The new buffer
bpb@12418 124 * will be direct if, and only if, this buffer is direct, and it will be
bpb@12418 125 * read-only if, and only if, this buffer is read-only. </p>
duke@0 126 *
duke@0 127 * @return A new $type$ buffer
duke@0 128 */
duke@0 129 public abstract $Type$Buffer as$Type$Buffer();
duke@0 130
duke@0 131 #end
duke@0 132
duke@0 133 }