1fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// Protocol Buffers - Google's data interchange format 2fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// Copyright 2008 Google Inc. All rights reserved. 3fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// http://code.google.com/p/protobuf/ 4fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// 5fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// Redistribution and use in source and binary forms, with or without 6fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// modification, are permitted provided that the following conditions are 7fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// met: 8fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// 9fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// * Redistributions of source code must retain the above copyright 10fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// notice, this list of conditions and the following disclaimer. 11fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// * Redistributions in binary form must reproduce the above 12fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// copyright notice, this list of conditions and the following disclaimer 13fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// in the documentation and/or other materials provided with the 14fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// distribution. 15fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// * Neither the name of Google Inc. nor the names of its 16fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// contributors may be used to endorse or promote products derived from 17fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// this software without specific prior written permission. 18fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// 19fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 31fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// TODO(kenton): Use generics? E.g. Builder<BuilderType extends Builder>, then 32fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville// mergeFrom*() could return BuilderType for better type-safety. 33fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 34fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savillepackage com.google.protobuf; 35fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 36fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savilleimport java.io.IOException; 37fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savilleimport java.io.InputStream; 38fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savilleimport java.io.OutputStream; 39fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 40fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville/** 41fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Abstract interface implemented by Protocol Message objects. 42fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 43fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p>This interface is implemented by all protocol message objects. Non-lite 44fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * messages additionally implement the Message interface, which is a subclass 45fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * of MessageLite. Use MessageLite instead when you only need the subset of 46fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * features which it supports -- namely, nothing that uses descriptors or 47fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * reflection. You can instruct the protocol compiler to generate classes 48fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * which implement only MessageLite, not the full Message interface, by adding 49fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * the follow line to the .proto file: 50fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <pre> 51fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * option optimize_for = LITE_RUNTIME; 52fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * </pre> 53fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 54fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p>This is particularly useful on resource-constrained systems where the 55fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * full protocol buffers runtime library is too big. 56fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 57fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p>Note that on non-constrained systems (e.g. servers) when you need to link 58fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * in lots of protocol definitions, a better way to reduce total code footprint 59fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * is to use {@code optimize_for = CODE_SIZE}. This will make the generated 60fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * code smaller while still supporting all the same features (at the expense of 61fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * speed). {@code optimize_for = LITE_RUNTIME} is best when you only have a 62fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * small number of message types linked into your binary, in which case the 63fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * size of the protocol buffers runtime itself is the biggest problem. 64fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 65fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * @author kenton@google.com Kenton Varda 66fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 67fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savillepublic interface MessageLite { 68fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 69fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Get an instance of the type with all fields set to their default values. 70fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * This may or may not be a singleton. This differs from the 71fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@code getDefaultInstance()} method of generated message classes in that 72fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * this method is an abstract method of the {@code MessageLite} interface 73fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * whereas {@code getDefaultInstance()} is a static method of a specific 74fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * class. They return the same thing. 75fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 76fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville MessageLite getDefaultInstanceForType(); 77fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 78fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 79fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Returns true if all required fields in the message and all embedded 80fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * messages are set, false otherwise. 81fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 82fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville boolean isInitialized(); 83fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 84fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 85fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Serializes the message and writes it to {@code output}. This does not 86fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * flush or close the stream. 87fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 88fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville void writeTo(CodedOutputStream output) throws IOException; 89fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 90fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 91fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Get the number of bytes required to encode this message. The result 92fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * is only computed on the first call and memoized after that. 93fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 94fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville int getSerializedSize(); 95fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 96fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // ----------------------------------------------------------------- 97fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // Convenience methods. 98fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 99fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 100fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Serializes the message to a {@code ByteString} and returns it. This is 101fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * just a trivial wrapper around 102fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #writeTo(CodedOutputStream)}. 103fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 104fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ByteString toByteString(); 105fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 106fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 107fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Serializes the message to a {@code byte} array and returns it. This is 108fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * just a trivial wrapper around 109fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #writeTo(CodedOutputStream)}. 110fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 111fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville byte[] toByteArray(); 112fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 113fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 114fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Serializes the message and writes it to {@code output}. This is just a 115fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * trivial wrapper around {@link #writeTo(CodedOutputStream)}. This does 116fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * not flush or close the stream. 117fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p> 118fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * NOTE: Protocol Buffers are not self-delimiting. Therefore, if you write 119fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * any more data to the stream after the message, you must somehow ensure 120fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * that the parser on the receiving end does not interpret this as being 121fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * part of the protocol message. This can be done e.g. by writing the size 122fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * of the message before the data, then making sure to limit the input to 123fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * that size on the receiving end (e.g. by wrapping the InputStream in one 124fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * which limits the input). Alternatively, just use 125fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #writeDelimitedTo(OutputStream)}. 126fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 127fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville void writeTo(OutputStream output) throws IOException; 128fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 129fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 130fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Like {@link #writeTo(OutputStream)}, but writes the size of the message 131fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * as a varint before writing the data. This allows more data to be written 132fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * to the stream after the message without the need to delimit the message 133fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * data yourself. Use {@link Builder#mergeDelimitedFrom(InputStream)} (or 134fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)}) 135fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * to parse messages written by this method. 136fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 137fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville void writeDelimitedTo(OutputStream output) throws IOException; 138fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 139fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // ================================================================= 140fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // Builders 141fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 142fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 143fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Constructs a new builder for a message of the same type as this message. 144fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 145fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder newBuilderForType(); 146fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 147fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 148fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Constructs a builder initialized with the current message. Use this to 149fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * derive a new message from the current one. 150fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 151fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder toBuilder(); 152fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 153fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 154fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Abstract interface implemented by Protocol Message builders. 155fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 156fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville interface Builder extends Cloneable { 157fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** Resets all fields to their default values. */ 158fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder clear(); 159fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 160fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 161fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Construct the final message. Once this is called, the Builder is no 162fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * longer valid, and calling any other method will result in undefined 163fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * behavior and may throw a NullPointerException. If you need to continue 164fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * working with the builder after calling {@code build()}, {@code clone()} 165fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * it first. 166fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * @throws UninitializedMessageException The message is missing one or more 167fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * required fields (i.e. {@link #isInitialized()} returns false). 168fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Use {@link #buildPartial()} to bypass this check. 169fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 170fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville MessageLite build(); 171fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 172fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 173fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Like {@link #build()}, but does not throw an exception if the message 174fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * is missing required fields. Instead, a partial message is returned. 175fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Once this is called, the Builder is no longer valid, and calling any 176fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * will result in undefined behavior and may throw a NullPointerException. 177fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 178fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * If you need to continue working with the builder after calling 179fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@code buildPartial()}, {@code clone()} it first. 180fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 181fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville MessageLite buildPartial(); 182fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 183fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 184fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Clones the Builder. 185fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * @see Object#clone() 186fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 187fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder clone(); 188fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 189fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 190fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Returns true if all required fields in the message and all embedded 191fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * messages are set, false otherwise. 192fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 193fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville boolean isInitialized(); 194fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 195fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 196fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parses a message of this type from the input and merges it with this 197fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message, as if using {@link Builder#mergeFrom(MessageLite)}. 198fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 199fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p>Warning: This does not verify that all required fields are present in 200fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * the input message. If you call {@link #build()} without setting all 201fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * required fields, it will throw an {@link UninitializedMessageException}, 202fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * which is a {@code RuntimeException} and thus might not be caught. There 203fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * are a few good ways to deal with this: 204fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <ul> 205fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <li>Call {@link #isInitialized()} to verify that all required fields 206fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * are set before building. 207fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <li>Parse the message separately using one of the static 208fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@code parseFrom} methods, then use {@link #mergeFrom(MessageLite)} 209fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * to merge it with this one. {@code parseFrom} will throw an 210fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link InvalidProtocolBufferException} (an {@code IOException}) 211fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * if some required fields are missing. 212fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <li>Use {@code buildPartial()} to build, which ignores missing 213fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * required fields. 214fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * </ul> 215fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * 216fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p>Note: The caller should call 217fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link CodedInputStream#checkLastTagWas(int)} after calling this to 218fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * verify that the last tag seen was the appropriate end-group tag, 219fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * or zero for EOF. 220fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 221fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(CodedInputStream input) throws IOException; 222fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 223fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 224fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Like {@link Builder#mergeFrom(CodedInputStream)}, but also 225fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * parses extensions. The extensions that you want to be able to parse 226fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * must be registered in {@code extensionRegistry}. Extensions not in 227fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * the registry will be treated as unknown fields. 228fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 229fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(CodedInputStream input, 230fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 231fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws IOException; 232fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 233fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 234fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Get the message's type's default instance. 235fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * See {@link MessageLite#getDefaultInstanceForType()}. 236fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 237fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville MessageLite getDefaultInstanceForType(); 238fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 239fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // --------------------------------------------------------------- 240fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville // Convenience methods. 241fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 242fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 243fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 244fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 245fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream)}. 246fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 247fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException; 248fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 249fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 250fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 251fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 252fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. 253fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 254fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(ByteString data, 255fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 256fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws InvalidProtocolBufferException; 257fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 258fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 259fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 260fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 261fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream)}. 262fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 263fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException; 264fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 265fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 266fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 267fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 268fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream)}. 269fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 270fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(byte[] data, int off, int len) 271fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws InvalidProtocolBufferException; 272fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 273fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 274fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 275fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 276fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. 277fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 278fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(byte[] data, 279fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 280fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws InvalidProtocolBufferException; 281fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 282fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 283fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse {@code data} as a message of this type and merge it with the 284fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 285fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. 286fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 287fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(byte[] data, int off, int len, 288fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 289fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws InvalidProtocolBufferException; 290fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 291fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 292fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse a message of this type from {@code input} and merge it with the 293fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 294fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream)}. Note that this method always 295fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * reads the <i>entire</i> input (unless it throws an exception). If you 296fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * want it to stop earlier, you will need to wrap your input in some 297fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * wrapper stream that limits reading. Or, use 298fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message 299fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * and {@link #mergeDelimitedFrom(InputStream)} to read it. 300fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * <p> 301fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Despite usually reading the entire input, this does not close the stream. 302fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 303fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(InputStream input) throws IOException; 304fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 305fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 306fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Parse a message of this type from {@code input} and merge it with the 307fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * message being built. This is just a small wrapper around 308fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. 309fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 310fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville Builder mergeFrom(InputStream input, 311fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 312fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws IOException; 313fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 314fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 315fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Like {@link #mergeFrom(InputStream)}, but does not read until EOF. 316fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Instead, the size of the message (encoded as a varint) is read first, 317fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * then the message data. Use 318fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * {@link MessageLite#writeDelimitedTo(OutputStream)} to write messages in 319fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * this format. 320d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville * 321d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville * @returns True if successful, or false if the stream is at EOF when the 322d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville * method starts. Any other error (including reaching EOF during 323d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville * parsing) will cause an exception to be thrown. 324fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 325d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville boolean mergeDelimitedFrom(InputStream input) 326fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws IOException; 327fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 328fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville /** 329fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions. 330fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville */ 331d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville boolean mergeDelimitedFrom(InputStream input, 332fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville ExtensionRegistryLite extensionRegistry) 333fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville throws IOException; 334fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville } 335fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville} 336