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