0,0 → 1,215 |
// 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.util.Map; |
|
/** |
* Abstract interface implemented by Protocol Message objects. |
* <p> |
* See also {@link MessageLite}, which defines most of the methods that typical |
* users care about. {@link Message} adds to it methods that are not available |
* in the "lite" runtime. The biggest added features are introspection and |
* reflection -- i.e., getting descriptors for the message type and accessing |
* the field values dynamically. |
* |
* @author kenton@google.com Kenton Varda |
*/ |
public interface Message extends MessageLite, MessageOrBuilder { |
|
// ----------------------------------------------------------------- |
// Comparison and hashing |
|
/** |
* Compares the specified object with this message for equality. Returns |
* <tt>true</tt> if the given object is a message of the same type (as |
* defined by {@code getDescriptorForType()}) and has identical values for |
* all of its fields. Subclasses must implement this; inheriting |
* {@code Object.equals()} is incorrect. |
* |
* @param other object to be compared for equality with this message |
* @return <tt>true</tt> if the specified object is equal to this message |
*/ |
@Override |
boolean equals(Object other); |
|
/** |
* Returns the hash code value for this message. The hash code of a message |
* should mix the message's type (object identity of the decsriptor) with its |
* contents (known and unknown field values). Subclasses must implement this; |
* inheriting {@code Object.hashCode()} is incorrect. |
* |
* @return the hash code value for this message |
* @see Map#hashCode() |
*/ |
@Override |
int hashCode(); |
|
// ----------------------------------------------------------------- |
// Convenience methods. |
|
/** |
* Converts the message to a string in protocol buffer text format. This is |
* just a trivial wrapper around {@link TextFormat#printToString(Message)}. |
*/ |
@Override |
String toString(); |
|
// ================================================================= |
// Builders |
|
// (From MessageLite, re-declared here only for return type covariance.) |
Builder newBuilderForType(); |
Builder toBuilder(); |
|
/** |
* Abstract interface implemented by Protocol Message builders. |
*/ |
interface Builder extends MessageLite.Builder, MessageOrBuilder { |
// (From MessageLite.Builder, re-declared here only for return type |
// covariance.) |
Builder clear(); |
|
/** |
* Merge {@code other} into the message being built. {@code other} must |
* have the exact same type as {@code this} (i.e. |
* {@code getDescriptorForType() == other.getDescriptorForType()}). |
* |
* 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. |
* |
* This is equivalent to the {@code Message::MergeFrom} method in C++. |
*/ |
Builder mergeFrom(Message other); |
|
// (From MessageLite.Builder, re-declared here only for return type |
// covariance.) |
Message build(); |
Message buildPartial(); |
Builder clone(); |
Builder mergeFrom(CodedInputStream input) throws IOException; |
Builder mergeFrom(CodedInputStream input, |
ExtensionRegistryLite extensionRegistry) |
throws IOException; |
|
/** |
* Get the message's type's descriptor. |
* See {@link Message#getDescriptorForType()}. |
*/ |
Descriptors.Descriptor getDescriptorForType(); |
|
/** |
* Create a Builder for messages of the appropriate type for the given |
* field. Messages built with this can then be passed to setField(), |
* setRepeatedField(), or addRepeatedField(). |
*/ |
Builder newBuilderForField(Descriptors.FieldDescriptor field); |
|
/** |
* Sets a field to the given value. The value must be of the correct type |
* for this field, i.e. the same type that |
* {@link Message#getField(Descriptors.FieldDescriptor)} would return. |
*/ |
Builder setField(Descriptors.FieldDescriptor field, Object value); |
|
/** |
* Clears the field. This is exactly equivalent to calling the generated |
* "clear" accessor method corresponding to the field. |
*/ |
Builder clearField(Descriptors.FieldDescriptor field); |
|
/** |
* Sets an element of a repeated field to the given value. The value must |
* be of the correct type for this field, i.e. the same type that |
* {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} would |
* return. |
* @throws IllegalArgumentException The field is not a repeated field, or |
* {@code field.getContainingType() != getDescriptorForType()}. |
*/ |
Builder setRepeatedField(Descriptors.FieldDescriptor field, |
int index, Object value); |
|
/** |
* Like {@code setRepeatedField}, but appends the value as a new element. |
* @throws IllegalArgumentException The field is not a repeated field, or |
* {@code field.getContainingType() != getDescriptorForType()}. |
*/ |
Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value); |
|
/** Set the {@link UnknownFieldSet} for this message. */ |
Builder setUnknownFields(UnknownFieldSet unknownFields); |
|
/** |
* Merge some unknown fields into the {@link UnknownFieldSet} for this |
* message. |
*/ |
Builder mergeUnknownFields(UnknownFieldSet unknownFields); |
|
// --------------------------------------------------------------- |
// Convenience methods. |
|
// (From MessageLite.Builder, re-declared here only for return type |
// covariance.) |
Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException; |
Builder mergeFrom(ByteString data, |
ExtensionRegistryLite extensionRegistry) |
throws InvalidProtocolBufferException; |
Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException; |
Builder mergeFrom(byte[] data, int off, int len) |
throws InvalidProtocolBufferException; |
Builder mergeFrom(byte[] data, |
ExtensionRegistryLite extensionRegistry) |
throws InvalidProtocolBufferException; |
Builder mergeFrom(byte[] data, int off, int len, |
ExtensionRegistryLite extensionRegistry) |
throws InvalidProtocolBufferException; |
Builder mergeFrom(InputStream input) throws IOException; |
Builder mergeFrom(InputStream input, |
ExtensionRegistryLite extensionRegistry) |
throws IOException; |
boolean mergeDelimitedFrom(InputStream input) |
throws IOException; |
boolean mergeDelimitedFrom(InputStream input, |
ExtensionRegistryLite extensionRegistry) |
throws IOException; |
} |
} |