/thirdparty/breakpad/third_party/protobuf/protobuf/java/src/main/java/com/google/protobuf/Message.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
 34package com.google.protobuf;
 35
 36import java.io.IOException;
 37import java.io.InputStream;
 38import java.util.Map;
 39
 40/**
 41 * Abstract interface implemented by Protocol Message objects.
 42 * <p>
 43 * See also {@link MessageLite}, which defines most of the methods that typical
 44 * users care about.  {@link Message} adds to it methods that are not available
 45 * in the "lite" runtime.  The biggest added features are introspection and
 46 * reflection -- i.e., getting descriptors for the message type and accessing
 47 * the field values dynamically.
 48 *
 49 * @author kenton@google.com Kenton Varda
 50 */
 51public interface Message extends MessageLite, MessageOrBuilder {
 52
 53  // -----------------------------------------------------------------
 54  // Comparison and hashing
 55
 56  /**
 57   * Compares the specified object with this message for equality.  Returns
 58   * <tt>true</tt> if the given object is a message of the same type (as
 59   * defined by {@code getDescriptorForType()}) and has identical values for
 60   * all of its fields.  Subclasses must implement this; inheriting
 61   * {@code Object.equals()} is incorrect.
 62   *
 63   * @param other object to be compared for equality with this message
 64   * @return <tt>true</tt> if the specified object is equal to this message
 65   */
 66  @Override
 67  boolean equals(Object other);
 68
 69  /**
 70   * Returns the hash code value for this message.  The hash code of a message
 71   * should mix the message's type (object identity of the decsriptor) with its
 72   * contents (known and unknown field values).  Subclasses must implement this;
 73   * inheriting {@code Object.hashCode()} is incorrect.
 74   *
 75   * @return the hash code value for this message
 76   * @see Map#hashCode()
 77   */
 78  @Override
 79  int hashCode();
 80
 81  // -----------------------------------------------------------------
 82  // Convenience methods.
 83
 84  /**
 85   * Converts the message to a string in protocol buffer text format. This is
 86   * just a trivial wrapper around {@link TextFormat#printToString(Message)}.
 87   */
 88  @Override
 89  String toString();
 90
 91  // =================================================================
 92  // Builders
 93
 94  // (From MessageLite, re-declared here only for return type covariance.)
 95  Builder newBuilderForType();
 96  Builder toBuilder();
 97
 98  /**
 99   * Abstract interface implemented by Protocol Message builders.
100   */
101  interface Builder extends MessageLite.Builder, MessageOrBuilder {
102    // (From MessageLite.Builder, re-declared here only for return type
103    // covariance.)
104    Builder clear();
105
106    /**
107     * Merge {@code other} into the message being built.  {@code other} must
108     * have the exact same type as {@code this} (i.e.
109     * {@code getDescriptorForType() == other.getDescriptorForType()}).
110     *
111     * Merging occurs as follows.  For each field:<br>
112     * * For singular primitive fields, if the field is set in {@code other},
113     *   then {@code other}'s value overwrites the value in this message.<br>
114     * * For singular message fields, if the field is set in {@code other},
115     *   it is merged into the corresponding sub-message of this message
116     *   using the same merging rules.<br>
117     * * For repeated fields, the elements in {@code other} are concatenated
118     *   with the elements in this message.
119     *
120     * This is equivalent to the {@code Message::MergeFrom} method in C++.
121     */
122    Builder mergeFrom(Message other);
123
124    // (From MessageLite.Builder, re-declared here only for return type
125    // covariance.)
126    Message build();
127    Message buildPartial();
128    Builder clone();
129    Builder mergeFrom(CodedInputStream input) throws IOException;
130    Builder mergeFrom(CodedInputStream input,
131                      ExtensionRegistryLite extensionRegistry)
132                      throws IOException;
133
134    /**
135     * Get the message's type's descriptor.
136     * See {@link Message#getDescriptorForType()}.
137     */
138    Descriptors.Descriptor getDescriptorForType();
139
140    /**
141     * Create a Builder for messages of the appropriate type for the given
142     * field.  Messages built with this can then be passed to setField(),
143     * setRepeatedField(), or addRepeatedField().
144     */
145    Builder newBuilderForField(Descriptors.FieldDescriptor field);
146
147    /**
148     * Sets a field to the given value.  The value must be of the correct type
149     * for this field, i.e. the same type that
150     * {@link Message#getField(Descriptors.FieldDescriptor)} would return.
151     */
152    Builder setField(Descriptors.FieldDescriptor field, Object value);
153
154    /**
155     * Clears the field.  This is exactly equivalent to calling the generated
156     * "clear" accessor method corresponding to the field.
157     */
158    Builder clearField(Descriptors.FieldDescriptor field);
159
160    /**
161     * Sets an element of a repeated field to the given value.  The value must
162     * be of the correct type for this field, i.e. the same type that
163     * {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} would
164     * return.
165     * @throws IllegalArgumentException The field is not a repeated field, or
166     *           {@code field.getContainingType() != getDescriptorForType()}.
167     */
168    Builder setRepeatedField(Descriptors.FieldDescriptor field,
169                             int index, Object value);
170
171    /**
172     * Like {@code setRepeatedField}, but appends the value as a new element.
173     * @throws IllegalArgumentException The field is not a repeated field, or
174     *           {@code field.getContainingType() != getDescriptorForType()}.
175     */
176    Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value);
177
178    /** Set the {@link UnknownFieldSet} for this message. */
179    Builder setUnknownFields(UnknownFieldSet unknownFields);
180
181    /**
182     * Merge some unknown fields into the {@link UnknownFieldSet} for this
183     * message.
184     */
185    Builder mergeUnknownFields(UnknownFieldSet unknownFields);
186
187    // ---------------------------------------------------------------
188    // Convenience methods.
189
190    // (From MessageLite.Builder, re-declared here only for return type
191    // covariance.)
192    Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
193    Builder mergeFrom(ByteString data,
194                      ExtensionRegistryLite extensionRegistry)
195                      throws InvalidProtocolBufferException;
196    Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
197    Builder mergeFrom(byte[] data, int off, int len)
198                      throws InvalidProtocolBufferException;
199    Builder mergeFrom(byte[] data,
200                      ExtensionRegistryLite extensionRegistry)
201                      throws InvalidProtocolBufferException;
202    Builder mergeFrom(byte[] data, int off, int len,
203                      ExtensionRegistryLite extensionRegistry)
204                      throws InvalidProtocolBufferException;
205    Builder mergeFrom(InputStream input) throws IOException;
206    Builder mergeFrom(InputStream input,
207                      ExtensionRegistryLite extensionRegistry)
208                      throws IOException;
209    boolean mergeDelimitedFrom(InputStream input)
210                               throws IOException;
211    boolean mergeDelimitedFrom(InputStream input,
212                               ExtensionRegistryLite extensionRegistry)
213                               throws IOException;
214  }
215}