1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc. All rights reserved.
3 // https://developers.google.com/protocol-buffers/
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
9 // * Redistributions of source code must retain the above copyright
10 // notice, this list of conditions and the following disclaimer.
11 // * Redistributions in binary form must reproduce the above
12 // copyright notice, this list of conditions and the following disclaimer
13 // in the documentation and/or other materials provided with the
15 // * Neither the name of Google Inc. nor the names of its
16 // contributors may be used to endorse or promote products derived from
17 // this software without specific prior written permission.
19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 package com.google.protobuf;
33 import java.io.IOException;
34 import java.nio.ByteBuffer;
37 * An output target for raw bytes. This interface provides semantics that support two types of
40 * <p><b>Traditional write operations:</b> (as defined by {@link java.io.OutputStream}) where the
41 * target method is responsible for either copying the data or completing the write before returning
42 * from the method call.
44 * <p><b>Lazy write operations:</b> where the caller guarantees that it will never modify the
45 * provided buffer and it can therefore be considered immutable. The target method is free to
46 * maintain a reference to the buffer beyond the scope of the method call (e.g. until the write
47 * operation completes).
50 public abstract class ByteOutput {
52 * Writes a single byte.
54 * @param value the byte to be written
55 * @throws IOException thrown if an error occurred while writing
57 public abstract void write(byte value) throws IOException;
60 * Writes a sequence of bytes. The {@link ByteOutput} must copy {@code value} if it will not be
61 * processed prior to the return of this method call, since {@code value} may be reused/altered by
64 * <p>NOTE: This method <strong>MUST NOT</strong> modify the {@code value}. Doing so is a
65 * programming error and will lead to data corruption which will be difficult to debug.
67 * @param value the bytes to be written
68 * @param offset the offset of the start of the writable range
69 * @param length the number of bytes to write starting from {@code offset}
70 * @throws IOException thrown if an error occurred while writing
72 public abstract void write(byte[] value, int offset, int length) throws IOException;
75 * Writes a sequence of bytes. The {@link ByteOutput} is free to retain a reference to the value
76 * beyond the scope of this method call (e.g. write later) since it is considered immutable and is
77 * guaranteed not to change by the caller.
79 * <p>NOTE: This method <strong>MUST NOT</strong> modify the {@code value}. Doing so is a
80 * programming error and will lead to data corruption which will be difficult to debug.
82 * @param value the bytes to be written
83 * @param offset the offset of the start of the writable range
84 * @param length the number of bytes to write starting from {@code offset}
85 * @throws IOException thrown if an error occurred while writing
87 public abstract void writeLazy(byte[] value, int offset, int length) throws IOException;
90 * Writes a sequence of bytes. The {@link ByteOutput} must copy {@code value} if it will not be
91 * processed prior to the return of this method call, since {@code value} may be reused/altered by
94 * <p>NOTE: This method <strong>MUST NOT</strong> modify the {@code value}. Doing so is a
95 * programming error and will lead to data corruption which will be difficult to debug.
97 * @param value the bytes to be written. Upon returning from this call, the {@code position} of
98 * this buffer will be set to the {@code limit}
99 * @throws IOException thrown if an error occurred while writing
101 public abstract void write(ByteBuffer value) throws IOException;
104 * Writes a sequence of bytes. The {@link ByteOutput} is free to retain a reference to the value
105 * beyond the scope of this method call (e.g. write later) since it is considered immutable and is
106 * guaranteed not to change by the caller.
108 * <p>NOTE: This method <strong>MUST NOT</strong> modify the {@code value}. Doing so is a
109 * programming error and will lead to data corruption which will be difficult to debug.
111 * @param value the bytes to be written. Upon returning from this call, the {@code position} of
112 * this buffer will be set to the {@code limit}
113 * @throws IOException thrown if an error occurred while writing
115 public abstract void writeLazy(ByteBuffer value) throws IOException;