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 // https://developers.google.com/protocol-buffers/
   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   // =================================================================
 133   // Builders
 134
 135   /**
 136    * Constructs a new builder for a message of the same type as this message.
 137    */
 138   Builder newBuilderForType();
 139
 140   /**
 141    * Constructs a builder initialized with the current message.  Use this to
 142    * derive a new message from the current one.
 143    */
 144   Builder toBuilder();
 145
 146   /**
 147    * Abstract interface implemented by Protocol Message builders.
 148    */
 149   interface Builder extends MessageLiteOrBuilder, Cloneable {
 150     /** Resets all fields to their default values. */
 151     Builder clear();
 152
 153     /**
 154      * Constructs the message based on the state of the Builder. Subsequent
 155      * changes to the Builder will not affect the returned message.
 156      * @throws UninitializedMessageException The message is missing one or more
 157      *         required fields (i.e. {@link #isInitialized()} returns false).
 158      *         Use {@link #buildPartial()} to bypass this check.
 159      */
 160     MessageLite build();
 161
 162     /**
 163      * Like {@link #build()}, but does not throw an exception if the message
 164      * is missing required fields.  Instead, a partial message is returned.
 165      * Subsequent changes to the Builder will not affect the returned message.
 166      */
 167     MessageLite buildPartial();
 168
 169     /**
 170      * Clones the Builder.
 171      * @see Object#clone()
 172      */
 173     Builder clone();
 174
 175     /**
 176      * Parses a message of this type from the input and merges it with this
 177      * message.
 178      *
 179      * <p>Warning:  This does not verify that all required fields are present in
 180      * the input message.  If you call {@link #build()} without setting all
 181      * required fields, it will throw an {@link UninitializedMessageException},
 182      * which is a {@code RuntimeException} and thus might not be caught.  There
 183      * are a few good ways to deal with this:
 184      * <ul>
 185      *   <li>Call {@link #isInitialized()} to verify that all required fields
 186      *       are set before building.
 187      *   <li>Use {@code buildPartial()} to build, which ignores missing
 188      *       required fields.
 189      * </ul>
 190      *
 191      * <p>Note:  The caller should call
 192      * {@link CodedInputStream#checkLastTagWas(int)} after calling this to
 193      * verify that the last tag seen was the appropriate end-group tag,
 194      * or zero for EOF.
 195      */
 196     Builder mergeFrom(CodedInputStream input) throws IOException;
 197
 198     /**
 199      * Like {@link Builder#mergeFrom(CodedInputStream)}, but also
 200      * parses extensions.  The extensions that you want to be able to parse
 201      * must be registered in {@code extensionRegistry}.  Extensions not in
 202      * the registry will be treated as unknown fields.
 203      */
 204     Builder mergeFrom(CodedInputStream input,
 205                       ExtensionRegistryLite extensionRegistry)
 206                       throws IOException;
 207
 208     // ---------------------------------------------------------------
 209     // Convenience methods.
 210
 211     /**
 212      * Parse {@code data} as a message of this type and merge it with the
 213      * message being built.  This is just a small wrapper around
 214      * {@link #mergeFrom(CodedInputStream)}.
 215      *
 216      * @return this
 217      */
 218     Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
 219
 220     /**
 221      * Parse {@code data} as a message of this type and merge it with the
 222      * message being built.  This is just a small wrapper around
 223      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 224      *
 225      * @return this
 226      */
 227     Builder mergeFrom(ByteString data,
 228                       ExtensionRegistryLite extensionRegistry)
 229                       throws InvalidProtocolBufferException;
 230
 231     /**
 232      * Parse {@code data} as a message of this type and merge it with the
 233      * message being built.  This is just a small wrapper around
 234      * {@link #mergeFrom(CodedInputStream)}.
 235      *
 236      * @return this
 237      */
 238     Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
 239
 240     /**
 241      * Parse {@code data} as a message of this type and merge it with the
 242      * message being built.  This is just a small wrapper around
 243      * {@link #mergeFrom(CodedInputStream)}.
 244      *
 245      * @return this
 246      */
 247     Builder mergeFrom(byte[] data, int off, int len)
 248                       throws InvalidProtocolBufferException;
 249
 250     /**
 251      * Parse {@code data} as a message of this type and merge it with the
 252      * message being built.  This is just a small wrapper around
 253      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 254      *
 255      * @return this
 256      */
 257     Builder mergeFrom(byte[] data,
 258                       ExtensionRegistryLite extensionRegistry)
 259                       throws InvalidProtocolBufferException;
 260
 261     /**
 262      * Parse {@code data} as a message of this type and merge it with the
 263      * message being built.  This is just a small wrapper around
 264      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 265      *
 266      * @return this
 267      */
 268     Builder mergeFrom(byte[] data, int off, int len,
 269                       ExtensionRegistryLite extensionRegistry)
 270                       throws InvalidProtocolBufferException;
 271
 272     /**
 273      * Parse a message of this type from {@code input} and merge it with the
 274      * message being built.  This is just a small wrapper around
 275      * {@link #mergeFrom(CodedInputStream)}.  Note that this method always
 276      * reads the <i>entire</i> input (unless it throws an exception).  If you
 277      * want it to stop earlier, you will need to wrap your input in some
 278      * wrapper stream that limits reading.  Or, use
 279      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message
 280      * and {@link #mergeDelimitedFrom(InputStream)} to read it.
 281      * <p>
 282      * Despite usually reading the entire input, this does not close the stream.
 283      *
 284      * @return this
 285      */
 286     Builder mergeFrom(InputStream input) throws IOException;
 287
 288     /**
 289      * Parse a message of this type from {@code input} and merge it with the
 290      * message being built.  This is just a small wrapper around
 291      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
 292      *
 293      * @return this
 294      */
 295     Builder mergeFrom(InputStream input,
 296                       ExtensionRegistryLite extensionRegistry)
 297                       throws IOException;
 298
 299     /**
 300      * Like {@link #mergeFrom(InputStream)}, but does not read until EOF.
 301      * Instead, the size of the message (encoded as a varint) is read first,
 302      * then the message data.  Use
 303      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write messages in
 304      * this format.
 305      *
 306      * @return True if successful, or false if the stream is at EOF when the
 307      *         method starts.  Any other error (including reaching EOF during
 308      *         parsing) will cause an exception to be thrown.
 309      */
 310     boolean mergeDelimitedFrom(InputStream input)
 311                                throws IOException;
 312
 313     /**
 314      * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions.
 315      */
 316     boolean mergeDelimitedFrom(InputStream input,
 317                                ExtensionRegistryLite extensionRegistry)
 318                                throws IOException;
 319   }
 320 }