https://developers.google.com/protocol-buffers/protobuf-java/: Core Protocol Buffers library. Protocol Buffers are a way of encoding structured data in an efficient yet extensible format. 
// Protocol Buffers - Google's data interchange format
// Copyright 2008 Google Inc.  All rights reserved.
// https://developers.google.com/protocol-buffers/
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

// TODO(kenton):  Use generics?  E.g. Builder<BuilderType extends Builder>, then
//   mergeFrom*() could return BuilderType for better type-safety.

package com.google.protobuf;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;


Abstract interface implemented by Protocol Message objects.

This interface is implemented by all protocol message objects. Non-lite messages additionally
implement the Message interface, which is a subclass of MessageLite. Use MessageLite instead when
you only need the subset of features which it supports -- namely, nothing that uses descriptors
or reflection. You can instruct the protocol compiler to generate classes which implement only
MessageLite, not the full Message interface, by adding the follow line to the .proto file:

  option optimize_for = LITE_RUNTIME;



This is particularly useful on resource-constrained systems where the full protocol buffers
runtime library is too big.

Note that on non-constrained systems (e.g. servers) when you need to link in lots of protocol definitions, a better way to reduce total code footprint is to use optimize_for =
CODE_SIZE. This will make the generated code smaller while still supporting all the same features (at the expense of speed). optimize_for = LITE_RUNTIME is best when you only have a small number of message types linked into your binary, in which case the size of the protocol buffers runtime itself is the biggest problem. 
Author:kenton@google.com Kenton Varda
/**
 * Abstract interface implemented by Protocol Message objects.
 *
 * <p>This interface is implemented by all protocol message objects. Non-lite messages additionally
 * implement the Message interface, which is a subclass of MessageLite. Use MessageLite instead when
 * you only need the subset of features which it supports -- namely, nothing that uses descriptors
 * or reflection. You can instruct the protocol compiler to generate classes which implement only
 * MessageLite, not the full Message interface, by adding the follow line to the .proto file:
 *
 * <pre>
 *   option optimize_for = LITE_RUNTIME;
 * </pre>
 *
 * <p>This is particularly useful on resource-constrained systems where the full protocol buffers
 * runtime library is too big.
 *
 * <p>Note that on non-constrained systems (e.g. servers) when you need to link in lots of protocol
 * definitions, a better way to reduce total code footprint is to use {@code optimize_for =
 * CODE_SIZE}. This will make the generated code smaller while still supporting all the same
 * features (at the expense of speed). {@code optimize_for = LITE_RUNTIME} is best when you only
 * have a small number of message types linked into your binary, in which case the size of the
 * protocol buffers runtime itself is the biggest problem.
 *
 * @author kenton@google.com Kenton Varda
 */
public interface MessageLite extends MessageLiteOrBuilder {

  
Serializes the message and writes it to output. This does not flush or close the stream. 
/**
   * Serializes the message and writes it to {@code output}. This does not flush or close the
   * stream.
   */
  void writeTo(CodedOutputStream output) throws IOException;

  
Get the number of bytes required to encode this message. The result is only computed on the
first call and memoized after that.

/**
   * Get the number of bytes required to encode this message. The result is only computed on the
   * first call and memoized after that.
   */
  int getSerializedSize();

  
Gets the parser for a message of the same type as this message. 
/** Gets the parser for a message of the same type as this message. */
  Parser<? extends MessageLite> getParserForType();

  // -----------------------------------------------------------------
  // Convenience methods.

  
Serializes the message to a ByteString and returns it. This is just a trivial wrapper around writeTo(CodedOutputStream). 
/**
   * Serializes the message to a {@code ByteString} and returns it. This is just a trivial wrapper
   * around {@link #writeTo(CodedOutputStream)}.
   */
  ByteString toByteString();

  
Serializes the message to a byte array and returns it. This is just a trivial wrapper around writeTo(CodedOutputStream). 
/**
   * Serializes the message to a {@code byte} array and returns it. This is just a trivial wrapper
   * around {@link #writeTo(CodedOutputStream)}.
   */
  byte[] toByteArray();

  
Serializes the message and writes it to output. This is just a trivial wrapper around writeTo(CodedOutputStream). This does not flush or close the stream. 
NOTE: Protocol Buffers are not self-delimiting. Therefore, if you write any more data to the stream after the message, you must somehow ensure that the parser on the receiving end does not interpret this as being part of the protocol message. This can be done e.g. by writing the size of the message before the data, then making sure to limit the input to that size on the receiving end (e.g. by wrapping the InputStream in one which limits the input). Alternatively, just use writeDelimitedTo(OutputStream). 
/**
   * Serializes the message and writes it to {@code output}. This is just a trivial wrapper around
   * {@link #writeTo(CodedOutputStream)}. This does not flush or close the stream.
   *
   * <p>NOTE: Protocol Buffers are not self-delimiting. Therefore, if you write any more data to the
   * stream after the message, you must somehow ensure that the parser on the receiving end does not
   * interpret this as being part of the protocol message. This can be done e.g. by writing the size
   * of the message before the data, then making sure to limit the input to that size on the
   * receiving end (e.g. by wrapping the InputStream in one which limits the input). Alternatively,
   * just use {@link #writeDelimitedTo(OutputStream)}.
   */
  void writeTo(OutputStream output) throws IOException;

  
Like writeTo(OutputStream), but writes the size of the message as a varint before writing the data. This allows more data to be written to the stream after the message without the need to delimit the message data yourself. Use Builder.mergeDelimitedFrom(InputStream) (or the static method 
YourMessageType.parseDelimitedFrom(InputStream)) to parse messages written by this method. 
/**
   * Like {@link #writeTo(OutputStream)}, but writes the size of the message as a varint before
   * writing the data. This allows more data to be written to the stream after the message without
   * the need to delimit the message data yourself. Use {@link
   * Builder#mergeDelimitedFrom(InputStream)} (or the static method {@code
   * YourMessageType.parseDelimitedFrom(InputStream)}) to parse messages written by this method.
   */
  void writeDelimitedTo(OutputStream output) throws IOException;


  // =================================================================
  // Builders

  
Constructs a new builder for a message of the same type as this message. 
/** Constructs a new builder for a message of the same type as this message. */
  Builder newBuilderForType();

  
Constructs a builder initialized with the current message. Use this to derive a new message
from the current one.

/**
   * Constructs a builder initialized with the current message. Use this to derive a new message
   * from the current one.
   */
  Builder toBuilder();

  
Abstract interface implemented by Protocol Message builders. 
/** Abstract interface implemented by Protocol Message builders. */
  interface Builder extends MessageLiteOrBuilder, Cloneable {
    
Resets all fields to their default values. 
/** Resets all fields to their default values. */
    Builder clear();

    
Constructs the message based on the state of the Builder. Subsequent changes to the Builder
will not affect the returned message.

Throws:
/**
     * Constructs the message based on the state of the Builder. Subsequent changes to the Builder
     * will not affect the returned message.
     *
     * @throws UninitializedMessageException The message is missing one or more required fields
     *     (i.e. {@link #isInitialized()} returns false). Use {@link #buildPartial()} to bypass this
     *     check.
     */
    MessageLite build();

    
Like build(), but does not throw an exception if the message is missing required fields. Instead, a partial message is returned. Subsequent changes to the Builder will not affect the returned message. 
/**
     * Like {@link #build()}, but does not throw an exception if the message is missing required
     * fields. Instead, a partial message is returned. Subsequent changes to the Builder will not
     * affect the returned message.
     */
    MessageLite buildPartial();

    
Clones the Builder.

See Also:
  • clone.clone()
/**
     * Clones the Builder.
     *
     * @see Object#clone()
     */
    Builder clone();

    
Parses a message of this type from the input and merges it with this message.

Warning: This does not verify that all required fields are present in the input message. If you call build() without setting all required fields, it will throw an UninitializedMessageException, which is a RuntimeException and thus might not be caught. There are a few good ways to deal with this: 


Note: The caller should call CodedInputStream.checkLastTagWas(int) after calling this to verify that the last tag seen was the appropriate end-group tag, or zero for EOF. 
/**
     * Parses a message of this type from the input and merges it with this message.
     *
     * <p>Warning: This does not verify that all required fields are present in the input message.
     * If you call {@link #build()} without setting all required fields, it will throw an {@link
     * UninitializedMessageException}, which is a {@code RuntimeException} and thus might not be
     * caught. There are a few good ways to deal with this:
     *
     * <ul>
     *   <li>Call {@link #isInitialized()} to verify that all required fields are set before
     *       building.
     *   <li>Use {@code buildPartial()} to build, which ignores missing required fields.
     * </ul>
     *
     * <p>Note: The caller should call {@link CodedInputStream#checkLastTagWas(int)} after calling
     * this to verify that the last tag seen was the appropriate end-group tag, or zero for EOF.
     */
    Builder mergeFrom(CodedInputStream input) throws IOException;

    
Like mergeFrom(CodedInputStream), but also parses extensions. The extensions that you want to be able to parse must be registered in extensionRegistry. Extensions not in the registry will be treated as unknown fields. 
/**
     * Like {@link Builder#mergeFrom(CodedInputStream)}, but also parses extensions. The extensions
     * that you want to be able to parse must be registered in {@code extensionRegistry}. Extensions
     * not in the registry will be treated as unknown fields.
     */
    Builder mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry)
        throws IOException;

    // ---------------------------------------------------------------
    // Convenience methods.

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream)}.
     *
     * @return this
     */
    Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream, ExtensionRegistryLite). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
     *
     * @return this
     */
    Builder mergeFrom(ByteString data, ExtensionRegistryLite extensionRegistry)
        throws InvalidProtocolBufferException;

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream)}.
     *
     * @return this
     */
    Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream)}.
     *
     * @return this
     */
    Builder mergeFrom(byte[] data, int off, int len) throws InvalidProtocolBufferException;

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream, ExtensionRegistryLite). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
     *
     * @return this
     */
    Builder mergeFrom(byte[] data, ExtensionRegistryLite extensionRegistry)
        throws InvalidProtocolBufferException;

    
Parse data as a message of this type and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream, ExtensionRegistryLite). 
Returns:this
/**
     * Parse {@code data} as a message of this type and merge it with the message being built. This
     * is just a small wrapper around {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
     *
     * @return this
     */
    Builder mergeFrom(byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry)
        throws InvalidProtocolBufferException;

    
Parse a message of this type from input and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream). Note that this method always reads the entire input (unless it throws an exception). If you want it to stop earlier, you will need to wrap your input in some wrapper stream that limits reading. Or, use MessageLite.writeDelimitedTo(OutputStream) to write your message and mergeDelimitedFrom(InputStream) to read it. 
Despite usually reading the entire input, this does not close the stream.

Returns:this
/**
     * Parse a message of this type from {@code input} and merge it with the message being built.
     * This is just a small wrapper around {@link #mergeFrom(CodedInputStream)}. Note that this
     * method always reads the <i>entire</i> input (unless it throws an exception). If you want it
     * to stop earlier, you will need to wrap your input in some wrapper stream that limits reading.
     * Or, use {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message and {@link
     * #mergeDelimitedFrom(InputStream)} to read it.
     *
     * <p>Despite usually reading the entire input, this does not close the stream.
     *
     * @return this
     */
    Builder mergeFrom(InputStream input) throws IOException;

    
Parse a message of this type from input and merge it with the message being built. This is just a small wrapper around mergeFrom(CodedInputStream, ExtensionRegistryLite). 
Returns:this
/**
     * Parse a message of this type from {@code input} and merge it with the message being built.
     * This is just a small wrapper around {@link
     * #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
     *
     * @return this
     */
    Builder mergeFrom(InputStream input, ExtensionRegistryLite extensionRegistry)
        throws IOException;

    
Merge other into the message being built. other must have the exact same type as this (i.e. getClass().equals(getDefaultInstanceForType().getClass())). 
Merging occurs as follows. For each field:
 * For singular primitive fields, if the field is set in other, then other's value overwrites the value in this message.
 * For singular message fields, if the field is set in other, it is merged into the corresponding sub-message of this message using the same merging rules.
 * For repeated fields, the elements in other are concatenated with the elements in this message. * For oneof groups, if the other message has one of the fields set, the group of this message is cleared and replaced by the field of the other message, so that the oneof constraint is preserved. 
This is equivalent to the Message::MergeFrom method in C++. 
/**
     * Merge {@code other} into the message being built. {@code other} must have the exact same type
     * as {@code this} (i.e. {@code getClass().equals(getDefaultInstanceForType().getClass())}).
     *
     * <p>Merging occurs as follows. For each field:<br>
     * * For singular primitive fields, if the field is set in {@code other}, then {@code other}'s
     * value overwrites the value in this message.<br>
     * * For singular message fields, if the field is set in {@code other}, it is merged into the
     * corresponding sub-message of this message using the same merging rules.<br>
     * * For repeated fields, the elements in {@code other} are concatenated with the elements in
     * this message. * For oneof groups, if the other message has one of the fields set, the group
     * of this message is cleared and replaced by the field of the other message, so that the oneof
     * constraint is preserved.
     *
     * <p>This is equivalent to the {@code Message::MergeFrom} method in C++.
     */
    Builder mergeFrom(MessageLite other);

    
Like mergeFrom(InputStream), but does not read until EOF. Instead, the size of the message (encoded as a varint) is read first, then the message data. Use MessageLite.writeDelimitedTo(OutputStream) to write messages in this format. 
Returns:True if successful, or false if the stream is at EOF when the method starts. Any
    other error (including reaching EOF during parsing) will cause an exception to be thrown.
/**
     * Like {@link #mergeFrom(InputStream)}, but does not read until EOF. Instead, the size of the
     * message (encoded as a varint) is read first, then the message data. Use {@link
     * MessageLite#writeDelimitedTo(OutputStream)} to write messages in this format.
     *
     * @return True if successful, or false if the stream is at EOF when the method starts. Any
     *     other error (including reaching EOF during parsing) will cause an exception to be thrown.
     */
    boolean mergeDelimitedFrom(InputStream input) throws IOException;

    
Like mergeDelimitedFrom(InputStream) but supporting extensions. 
/** Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions. */
    boolean mergeDelimitedFrom(InputStream input, ExtensionRegistryLite extensionRegistry)
        throws IOException;
  }
}