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 // 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.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  */
  51 public interface Message extends MessageLite, MessageOrBuilder {
  52
  53   // (From MessageLite, re-declared here only for return type covariance.)
  54   Parser<? extends Message> getParserForType();
  55
  56
  57   // -----------------------------------------------------------------
  58   // Comparison and hashing
  59
  60   /**
  61    * Compares the specified object with this message for equality.  Returns
  62    * {@code true} if the given object is a message of the same type (as
  63    * defined by {@code getDescriptorForType()}) and has identical values for
  64    * all of its fields.  Subclasses must implement this; inheriting
  65    * {@code Object.equals()} is incorrect.
  66    *
  67    * @param other object to be compared for equality with this message
  68    * @return {@code true} if the specified object is equal to this message
  69    */
  70   @Override
  71   boolean equals(Object other);
  72
  73   /**
  74    * Returns the hash code value for this message.  The hash code of a message
  75    * should mix the message's type (object identity of the descriptor) with its
  76    * contents (known and unknown field values).  Subclasses must implement this;
  77    * inheriting {@code Object.hashCode()} is incorrect.
  78    *
  79    * @return the hash code value for this message
  80    * @see Map#hashCode()
  81    */
  82   @Override
  83   int hashCode();
  84
  85   // -----------------------------------------------------------------
  86   // Convenience methods.
  87
  88   /**
  89    * Converts the message to a string in protocol buffer text format. This is
  90    * just a trivial wrapper around {@link
  91    * TextFormat#printToString(MessageOrBuilder)}.
  92    */
  93   @Override
  94   String toString();
  95
  96   // =================================================================
  97   // Builders
  98
  99   // (From MessageLite, re-declared here only for return type covariance.)
 100   Builder newBuilderForType();
 101   Builder toBuilder();
 102
 103   /**
 104    * Abstract interface implemented by Protocol Message builders.
 105    */
 106   interface Builder extends MessageLite.Builder, MessageOrBuilder {
 107     // (From MessageLite.Builder, re-declared here only for return type
 108     // covariance.)
 109     Builder clear();
 110
 111     /**
 112      * Merge {@code other} into the message being built.  {@code other} must
 113      * have the exact same type as {@code this} (i.e.
 114      * {@code getDescriptorForType() == other.getDescriptorForType()}).
 115      *
 116      * Merging occurs as follows.  For each field:<br>
 117      * * For singular primitive fields, if the field is set in {@code other},
 118      *   then {@code other}'s value overwrites the value in this message.<br>
 119      * * For singular message fields, if the field is set in {@code other},
 120      *   it is merged into the corresponding sub-message of this message
 121      *   using the same merging rules.<br>
 122      * * For repeated fields, the elements in {@code other} are concatenated
 123      *   with the elements in this message.
 124      *
 125      * This is equivalent to the {@code Message::MergeFrom} method in C++.
 126      */
 127     Builder mergeFrom(Message other);
 128
 129     // (From MessageLite.Builder, re-declared here only for return type
 130     // covariance.)
 131     Message build();
 132     Message buildPartial();
 133     Builder clone();
 134     Builder mergeFrom(CodedInputStream input) throws IOException;
 135     Builder mergeFrom(CodedInputStream input,
 136                       ExtensionRegistryLite extensionRegistry)
 137                       throws IOException;
 138
 139     /**
 140      * Get the message's type's descriptor.
 141      * See {@link Message#getDescriptorForType()}.
 142      */
 143     Descriptors.Descriptor getDescriptorForType();
 144
 145     /**
 146      * Create a Builder for messages of the appropriate type for the given
 147      * field.  Messages built with this can then be passed to setField(),
 148      * setRepeatedField(), or addRepeatedField().
 149      */
 150     Builder newBuilderForField(Descriptors.FieldDescriptor field);
 151
 152     /**
 153      * Get a nested builder instance for the given field.
 154      * <p>
 155      * Normally, we hold a reference to the immutable message object for the
 156      * message type field. Some implementations(the generated message builders),
 157      * however, can also hold a reference to the builder object (a nested
 158      * builder) for the field.
 159      * <p>
 160      * If the field is already backed up by a nested builder, the nested builder
 161      * will be returned. Otherwise, a new field builder will be created and
 162      * returned. The original message field (if exist) will be merged into the
 163      * field builder, which will then be nested into its parent builder.
 164      * <p>
 165      * NOTE: implementations that do not support nested builders will throw
 166      * <code>UnsupportedException</code>.
 167      */
 168     Builder getFieldBuilder(Descriptors.FieldDescriptor field);
 169
 170     /**
 171      * Sets a field to the given value.  The value must be of the correct type
 172      * for this field, i.e. the same type that
 173      * {@link Message#getField(Descriptors.FieldDescriptor)} would return.
 174      */
 175     Builder setField(Descriptors.FieldDescriptor field, Object value);
 176
 177     /**
 178      * Clears the field.  This is exactly equivalent to calling the generated
 179      * "clear" accessor method corresponding to the field.
 180      */
 181     Builder clearField(Descriptors.FieldDescriptor field);
 182
 183     /**
 184      * Clears the oneof.  This is exactly equivalent to calling the generated
 185      * "clear" accessor method corresponding to the oneof.
 186      */
 187     Builder clearOneof(Descriptors.OneofDescriptor oneof);
 188
 189     /**
 190      * Sets an element of a repeated field to the given value.  The value must
 191      * be of the correct type for this field, i.e. the same type that
 192      * {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} would
 193      * return.
 194      * @throws IllegalArgumentException The field is not a repeated field, or
 195      *           {@code field.getContainingType() != getDescriptorForType()}.
 196      */
 197     Builder setRepeatedField(Descriptors.FieldDescriptor field,
 198                              int index, Object value);
 199
 200     /**
 201      * Like {@code setRepeatedField}, but appends the value as a new element.
 202      * @throws IllegalArgumentException The field is not a repeated field, or
 203      *           {@code field.getContainingType() != getDescriptorForType()}.
 204      */
 205     Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value);
 206
 207     /** Set the {@link UnknownFieldSet} for this message. */
 208     Builder setUnknownFields(UnknownFieldSet unknownFields);
 209
 210     /**
 211      * Merge some unknown fields into the {@link UnknownFieldSet} for this
 212      * message.
 213      */
 214     Builder mergeUnknownFields(UnknownFieldSet unknownFields);
 215
 216     // ---------------------------------------------------------------
 217     // Convenience methods.
 218
 219     // (From MessageLite.Builder, re-declared here only for return type
 220     // covariance.)
 221     Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
 222     Builder mergeFrom(ByteString data,
 223                       ExtensionRegistryLite extensionRegistry)
 224                       throws InvalidProtocolBufferException;
 225     Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
 226     Builder mergeFrom(byte[] data, int off, int len)
 227                       throws InvalidProtocolBufferException;
 228     Builder mergeFrom(byte[] data,
 229                       ExtensionRegistryLite extensionRegistry)
 230                       throws InvalidProtocolBufferException;
 231     Builder mergeFrom(byte[] data, int off, int len,
 232                       ExtensionRegistryLite extensionRegistry)
 233                       throws InvalidProtocolBufferException;
 234     Builder mergeFrom(InputStream input) throws IOException;
 235     Builder mergeFrom(InputStream input,
 236                       ExtensionRegistryLite extensionRegistry)
 237                       throws IOException;
 238     boolean mergeDelimitedFrom(InputStream input)
 239                                throws IOException;
 240     boolean mergeDelimitedFrom(InputStream input,
 241                                ExtensionRegistryLite extensionRegistry)
 242                                throws IOException;
 243   }
 244 }