/thirdparty/breakpad/third_party/protobuf/protobuf/java/src/main/java/com/google/protobuf/Message.java

http://github.com/tomahawk-player/tomahawk · Java · 215 lines · 56 code · 24 blank · 135 comment · 0 complexity · acdc0ec75183e11b6b8812ea6bcf01ab MD5 · raw file

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