/game_server/src/com/google/protobuf/MessageLite.java
Java | 325 lines | 46 code | 32 blank | 247 comment | 0 complexity | bc483eec5b6489fb83ff725421011ffb MD5 | raw file
- // Protocol Buffers - Google's data interchange format
- // Copyright 2008 Google Inc. All rights reserved.
- // http://code.google.com/p/protobuf/
- //
- // 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.
- *
- * <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 {@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.
- */
- int getSerializedSize();
- // -----------------------------------------------------------------
- // Convenience methods.
- /**
- * 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 {@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 {@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(java.io.OutputStream)}.
- */
- void writeTo(OutputStream output) throws IOException;
- /**
- * Like {@link #writeTo(java.io.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 com.google.protobuf.MessageLite.Builder#mergeDelimitedFrom(java.io.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.
- */
- Builder newBuilderForType();
- /**
- * 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.
- */
- interface Builder extends MessageLiteOrBuilder, Cloneable {
- /** Resets all fields to their default values. */
- Builder clear();
- /**
- * Construct the final message. Once this is called, the Builder is no
- * longer valid, and calling any other method will result in undefined
- * behavior and may throw a NullPointerException. If you need to continue
- * working with the builder after calling {@code build()}, {@code clone()}
- * it first.
- * @throws com.google.protobuf.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 {@link #build()}, but does not throw an exception if the message
- * is missing required fields. Instead, a partial message is returned.
- * Once this is called, the Builder is no longer valid, and calling any
- * will result in undefined behavior and may throw a NullPointerException.
- *
- * If you need to continue working with the builder after calling
- * {@code buildPartial()}, {@code clone()} it first.
- */
- MessageLite buildPartial();
- /**
- * Clones the Builder.
- * @see Object#clone()
- */
- Builder clone();
- /**
- * Parses a message of this type from the input and merges it with this
- * message, as if using {@link com.google.protobuf.MessageLite.Builder#mergeFrom(MessageLite)}.
- *
- * <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 com.google.protobuf.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>Parse the message separately using one of the static
- * {@code parseFrom} methods, then use {@link #mergeFrom(MessageLite)}
- * to merge it with this one. {@code parseFrom} will throw an
- * {@link InvalidProtocolBufferException} (an {@code IOException})
- * if some required fields are missing.
- * <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 {@link com.google.protobuf.MessageLite.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 {@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 {@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, ExtensionRegistry)}.
- *
- * @return this
- */
- Builder mergeFrom(ByteString data,
- ExtensionRegistryLite extensionRegistry)
- throws InvalidProtocolBufferException;
- /**
- * 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 {@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 {@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, ExtensionRegistry)}.
- *
- * @return this
- */
- Builder mergeFrom(byte[] data,
- ExtensionRegistryLite extensionRegistry)
- throws InvalidProtocolBufferException;
- /**
- * 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, ExtensionRegistry)}.
- *
- * @return this
- */
- Builder mergeFrom(byte[] data, int off, int len,
- ExtensionRegistryLite extensionRegistry)
- throws InvalidProtocolBufferException;
- /**
- * 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(java.io.OutputStream)} to write your message
- * and {@link #mergeDelimitedFrom(java.io.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 {@code input} and merge it with the
- * message being built. This is just a small wrapper around
- * {@link #mergeFrom(CodedInputStream, ExtensionRegistry)}.
- *
- * @return this
- */
- Builder mergeFrom(InputStream input,
- ExtensionRegistryLite extensionRegistry)
- throws IOException;
- /**
- * Like {@link #mergeFrom(java.io.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(java.io.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.
- */
- boolean mergeDelimitedFrom(InputStream input)
- throws IOException;
- /**
- * Like {@link #mergeDelimitedFrom(java.io.InputStream)} but supporting extensions.
- */
- boolean mergeDelimitedFrom(InputStream input,
- ExtensionRegistryLite extensionRegistry)
- throws IOException;
- }
- }