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 * Provides a number of unsafe byte operations to be used by advanced applications with high 38b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * performance requirements. These methods are referred to as "unsafe" due to the fact that they 39b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * potentially expose the backing buffer of a {@link ByteString} to the application. 40b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * 41b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * <p><strong>DISCLAIMER:</strong> The methods in this class should only be called if it is 42b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * guaranteed that the buffer backing the {@link ByteString} will never change! Mutation of a 43b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * {@link ByteString} can lead to unexpected and undesirable consequences in your application, 44b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * and will likely be difficult to debug. Proceed with caution! 45b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer */ 46b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer@ExperimentalApi 47b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammerpublic final class UnsafeByteOperations { 48b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer private UnsafeByteOperations() {} 49b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer 50b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer /** 51b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * An unsafe operation that returns a {@link ByteString} that is backed by the provided buffer. 52b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * 53b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * @param buffer the Java NIO buffer to be wrapped 54b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * @return a {@link ByteString} backed by the provided buffer 55b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer */ 56b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer public static ByteString unsafeWrap(ByteBuffer buffer) { 57b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer if (buffer.hasArray()) { 58b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer final int offset = buffer.arrayOffset(); 59b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer return ByteString.wrap(buffer.array(), offset + buffer.position(), buffer.remaining()); 60b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer } else { 61b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer return new NioByteString(buffer); 62b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer } 63b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer } 64b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer 65b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer /** 66b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * Writes the given {@link ByteString} to the provided {@link ByteOutput}. Calling this method may 67b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * result in multiple operations on the target {@link ByteOutput} 68b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * (i.e. for roped {@link ByteString}s). 69b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * 70b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * <p>This method exposes the internal backing buffer(s) of the {@link ByteString} to the {@link 71b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * ByteOutput} in order to avoid additional copying overhead. It would be possible for a malicious 72b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * {@link ByteOutput} to corrupt the {@link ByteString}. Use with caution! 73b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * 74b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * <p> NOTE: The {@link ByteOutput} <strong>MUST NOT</strong> modify the provided buffers. Doing 75b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * so may result in corrupted data, which would be difficult to debug. 76b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * 77b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * @param bytes the {@link ByteString} to be written 78b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * @param output the output to receive the bytes 79b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer * @throws IOException if an I/O error occurs 80b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer */ 81b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer public static void unsafeWriteTo(ByteString bytes, ByteOutput output) throws IOException { 82b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer bytes.writeTo(output); 83b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer } 84b0575e93e4c39dec69365b850088a1eb7f82c5b3Tamas Berghammer} 85