src/third_party/protobuf/java/src/main/java/com/google/protobuf/MessageLite.java

   1 // Protocol Buffers - Google's data interchange format
   2 // Copyright 2008 Google Inc.  All rights reserved.
   3 // http://code.google.com/p/protobuf/
   4 //
   5 // Redistribution and use in source and binary forms, with or without
   6 // modification, are permitted provided that the following conditions are
   7 // met:
   8 //
   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
  14 // distribution.
  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.
  18 //
  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.
  30
  31 // TODO(kenton):  Use generics?  E.g. Builder<BuilderType extends Builder>, then
  32 //   mergeFrom*() could return BuilderType for better type-safety.
  33
  34 package com.google.protobuf;
  35
  36 import java.io.IOException;
  37 import java.io.InputStream;
  38 import java.io.OutputStream;
  39
  40 /**
  41  * Abstract interface implemented by Protocol Message objects.
  42  *
  43  * <p>This interface is implemented by all protocol message objects.  Non-lite
  44  * messages additionally implement the Message interface, which is a subclass
  45  * of MessageLite.  Use MessageLite instead when you only need the subset of
  46  * features which it supports -- namely, nothing that uses descriptors or
  47  * reflection.  You can instruct the protocol compiler to generate classes
  48  * which implement only MessageLite, not the full Message interface, by adding
  49  * the follow line to the .proto file:
  50  * <pre>
  51  *   option optimize_for = LITE_RUNTIME;
  52  * </pre>
  53  *
  54  * <p>This is particularly useful on resource-constrained systems where the
  55  * full protocol buffers runtime library is too big.
  56  *
  57  * <p>Note that on non-constrained systems (e.g. servers) when you need to link
  58  * in lots of protocol definitions, a better way to reduce total code footprint
  59  * is to use {@code optimize_for = CODE_SIZE}.  This will make the generated
  60  * code smaller while still supporting all the same features (at the expense of
  61  * speed).  {@code optimize_for = LITE_RUNTIME} is best when you only have a
  62  * small number of message types linked into your binary, in which case the
  63  * size of the protocol buffers runtime itself is the biggest problem.
  64  *
  65  * @author kenton@google.com Kenton Varda
  66  */
  67 public interface MessageLite extends MessageLiteOrBuilder {
  68
  69
  70   /**
  71    * Serializes the message and writes it to {@code output}.  This does not
  72    * flush or close the stream.
  73    */
  74   void writeTo(CodedOutputStream output) throws IOException;
  75
  76   /**
  77    * Get the number of bytes required to encode this message.  The result
  78    * is only computed on the first call and memoized after that.
  79    */
  80   int getSerializedSize();
  81
  82
  83   /**
  84    * Gets the parser for a message of the same type as this message.
  85    */
  86   Parser<? extends MessageLite> getParserForType();
  87
  88   // -----------------------------------------------------------------
  89   // Convenience methods.
  90
  91   /**
  92    * Serializes the message to a {@code ByteString} and returns it. This is
  93    * just a trivial wrapper around
  94    * {@link #writeTo(CodedOutputStream)}.
  95    */
  96   ByteString toByteString();
  97
  98   /**
  99    * Serializes the message to a {@code byte} array and returns it.  This is
 100    * just a trivial wrapper around
 101    * {@link #writeTo(CodedOutputStream)}.
 102    */
 103   byte[] toByteArray();
 104
 105   /**
 106    * Serializes the message and writes it to {@code output}.  This is just a
 107    * trivial wrapper around {@link #writeTo(CodedOutputStream)}.  This does
 108    * not flush or close the stream.
 109    * <p>
 110    * NOTE:  Protocol Buffers are not self-delimiting.  Therefore, if you write
 111    * any more data to the stream after the message, you must somehow ensure
 112    * that the parser on the receiving end does not interpret this as being
 113    * part of the protocol message.  This can be done e.g. by writing the size
 114    * of the message before the data, then making sure to limit the input to
 115    * that size on the receiving end (e.g. by wrapping the InputStream in one
 116    * which limits the input).  Alternatively, just use
 117    * {@link #writeDelimitedTo(OutputStream)}.
 118    */
 119   void writeTo(OutputStream output) throws IOException;
 120
 121   /**
 122    * Like {@link #writeTo(OutputStream)}, but writes the size of the message
 123    * as a varint before writing the data.  This allows more data to be written
 124    * to the stream after the message without the need to delimit the message
 125    * data yourself.  Use {@link Builder#mergeDelimitedFrom(InputStream)} (or
 126    * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)})
 127    * to parse messages written by this method.
 128    */
 129   void writeDelimitedTo(OutputStream output) throws IOException;
 130
 131   // =================================================================
 132   // Builders
 133
 134   /**
 135    * Constructs a new builder for a message of the same type as this message.
 136    */
 137   Builder newBuilderForType();
 138
 139   /**
 140    * Constructs a builder initialized with the current message.  Use this to
 141    * derive a new message from the current one.
 142    */
 143   Builder toBuilder();
 144
 145   /**
 146    * Abstract interface implemented by Protocol Message builders.
 147    */
 148   interface Builder extends MessageLiteOrBuilder, Cloneable {
 149     /** Resets all fields to their default values. */
 150     Builder clear();
 151
 152     /**
 153      * Constructs the message based on the state of the Builder. Subsequent
 154      * changes to the Builder will not affect the returned message.
 155      * @throws UninitializedMessageException The message is missing one or more
 156      *         required fields (i.e. {@link #isInitialized()} returns false).
 157      *         Use {@link #buildPartial()} to bypass this check.
 158      */
 159     MessageLite build();
 160
 161     /**
 162      * Like {@link #build()}, but does not throw an exception if the message
 163      * is missing required fields.  Instead, a partial message is returned.
 164      * Subsequent changes to the Builder will not affect the returned message.
 165      */
 166     MessageLite buildPartial();
 167
 168     /**
 169      * Clones the Builder.
 170      * @see Object#clone()
 171      */
 172     Builder clone();
 173
 174     /**
 175      * Parses a message of this type from the input and merges it with this
 176      * message.
 177      *
 178      * <p>Warning:  This does not verify that all required fields are present in
 179      * the input message.  If you call {@link #build()} without setting all
 180      * required fields, it will throw an {@link UninitializedMessageException},
 181      * which is a {@code RuntimeException} and thus might not be caught.  There
 182      * are a few good ways to deal with this:
 183      * <ul>
 184      *   <li>Call {@link #isInitialized()} to verify that all required fields
 185      *       are set before building.
 186      *   <li>Use {@code buildPartial()} to build, which ignores missing
 187      *       required fields.
 188      * </ul>
 189      *
 190      * <p>Note:  The caller should call
 191      * {@link CodedInputStream#checkLastTagWas(int)} after calling this to
 192      * verify that the last tag seen was the appropriate end-group tag,
 193      * or zero for EOF.
 194      */
 195     Builder mergeFrom(CodedInputStream input) throws IOException;
 196
 197     /**
 198      * Like {@link Builder#mergeFrom(CodedInputStream)}, but also
 199      * parses extensions.  The extensions that you want to be able to parse
 200      * must be registered in {@code extensionRegistry}.  Extensions not in
 201      * the registry will be treated as unknown fields.
 202      */
 203     Builder mergeFrom(CodedInputStream input,
 204                       ExtensionRegistryLite extensionRegistry)
 205                       throws IOException;
 206
 207     // ---------------------------------------------------------------
 208     // Convenience methods.
 209
 210     /**
 211      * Parse {@code data} as a message of this type and merge it with the
 212      * message being built.  This is just a small wrapper around
 213      * {@link #mergeFrom(CodedInputStream)}.
 214      *
 215      * @return this
 216      */
 217     Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
 218
 219     /**
 220      * Parse {@code data} as a message of this type and merge it with the
 221      * message being built.  This is just a small wrapper around
 222      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 223      *
 224      * @return this
 225      */
 226     Builder mergeFrom(ByteString data,
 227                       ExtensionRegistryLite extensionRegistry)
 228                       throws InvalidProtocolBufferException;
 229
 230     /**
 231      * Parse {@code data} as a message of this type and merge it with the
 232      * message being built.  This is just a small wrapper around
 233      * {@link #mergeFrom(CodedInputStream)}.
 234      *
 235      * @return this
 236      */
 237     Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
 238
 239     /**
 240      * Parse {@code data} as a message of this type and merge it with the
 241      * message being built.  This is just a small wrapper around
 242      * {@link #mergeFrom(CodedInputStream)}.
 243      *
 244      * @return this
 245      */
 246     Builder mergeFrom(byte[] data, int off, int len)
 247                       throws InvalidProtocolBufferException;
 248
 249     /**
 250      * Parse {@code data} as a message of this type and merge it with the
 251      * message being built.  This is just a small wrapper around
 252      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 253      *
 254      * @return this
 255      */
 256     Builder mergeFrom(byte[] data,
 257                       ExtensionRegistryLite extensionRegistry)
 258                       throws InvalidProtocolBufferException;
 259
 260     /**
 261      * Parse {@code data} as a message of this type and merge it with the
 262      * message being built.  This is just a small wrapper around
 263      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 264      *
 265      * @return this
 266      */
 267     Builder mergeFrom(byte[] data, int off, int len,
 268                       ExtensionRegistryLite extensionRegistry)
 269                       throws InvalidProtocolBufferException;
 270
 271     /**
 272      * Parse a message of this type from {@code input} and merge it with the
 273      * message being built.  This is just a small wrapper around
 274      * {@link #mergeFrom(CodedInputStream)}.  Note that this method always
 275      * reads the <i>entire</i> input (unless it throws an exception).  If you
 276      * want it to stop earlier, you will need to wrap your input in some
 277      * wrapper stream that limits reading.  Or, use
 278      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message
 279      * and {@link #mergeDelimitedFrom(InputStream)} to read it.
 280      * <p>
 281      * Despite usually reading the entire input, this does not close the stream.
 282      *
 283      * @return this
 284      */
 285     Builder mergeFrom(InputStream input) throws IOException;
 286
 287     /**
 288      * Parse a message of this type from {@code input} and merge it with the
 289      * message being built.  This is just a small wrapper around
 290      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 291      *
 292      * @return this
 293      */
 294     Builder mergeFrom(InputStream input,
 295                       ExtensionRegistryLite extensionRegistry)
 296                       throws IOException;
 297
 298     /**
 299      * Like {@link #mergeFrom(InputStream)}, but does not read until EOF.
 300      * Instead, the size of the message (encoded as a varint) is read first,
 301      * then the message data.  Use
 302      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write messages in
 303      * this format.
 304      *
 305      * @return True if successful, or false if the stream is at EOF when the
 306      *         method starts.  Any other error (including reaching EOF during
 307      *         parsing) will cause an exception to be thrown.
 308      */
 309     boolean mergeDelimitedFrom(InputStream input)
 310                                throws IOException;
 311
 312     /**
 313      * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions.
 314      */
 315     boolean mergeDelimitedFrom(InputStream input,
 316                                ExtensionRegistryLite extensionRegistry)
 317                                throws IOException;
 318   }
 319 }