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 { 52 /** 53 * Get the message's type's descriptor. This differs from the 54 * {@code getDescriptor()} method of generated message classes in that 55 * this method is an abstract method of the {@code Message} interface 56 * whereas {@code getDescriptor()} is a static method of a specific class. 57 * They return the same thing. 58 */ 59 Descriptors.Descriptor getDescriptorForType(); 60 61 // (From MessageLite, re-declared here only for return type covariance.) 62 Message getDefaultInstanceForType(); 63 64 /** 65 * Returns a collection of all the fields in this message which are set 66 * and their corresponding values. A singular ("required" or "optional") 67 * field is set iff hasField() returns true for that field. A "repeated" 68 * field is set iff getRepeatedFieldSize() is greater than zero. The 69 * values are exactly what would be returned by calling 70 * {@link #getField(Descriptors.FieldDescriptor)} for each field. The map 71 * is guaranteed to be a sorted map, so iterating over it will return fields 72 * in order by field number. 73 */ 74 Map<Descriptors.FieldDescriptor, Object> getAllFields(); 75 76 /** 77 * Returns true if the given field is set. This is exactly equivalent to 78 * calling the generated "has" accessor method corresponding to the field. 79 * @throws IllegalArgumentException The field is a repeated field, or 80 * {@code field.getContainingType() != getDescriptorForType()}. 81 */ 82 boolean hasField(Descriptors.FieldDescriptor field); 83 84 /** 85 * Obtains the value of the given field, or the default value if it is 86 * not set. For primitive fields, the boxed primitive value is returned. 87 * For enum fields, the EnumValueDescriptor for the value is returend. For 88 * embedded message fields, the sub-message is returned. For repeated 89 * fields, a java.util.List is returned. 90 */ 91 Object getField(Descriptors.FieldDescriptor field); 92 93 /** 94 * Gets the number of elements of a repeated field. This is exactly 95 * equivalent to calling the generated "Count" accessor method corresponding 96 * to the field. 97 * @throws IllegalArgumentException The field is not a repeated field, or 98 * {@code field.getContainingType() != getDescriptorForType()}. 99 */ 100 int getRepeatedFieldCount(Descriptors.FieldDescriptor field); 101 102 /** 103 * Gets an element of a repeated field. For primitive fields, the boxed 104 * primitive value is returned. For enum fields, the EnumValueDescriptor 105 * for the value is returend. For embedded message fields, the sub-message 106 * is returned. 107 * @throws IllegalArgumentException The field is not a repeated field, or 108 * {@code field.getContainingType() != getDescriptorForType()}. 109 */ 110 Object getRepeatedField(Descriptors.FieldDescriptor field, int index); 111 112 /** Get the {@link UnknownFieldSet} for this message. */ 113 UnknownFieldSet getUnknownFields(); 114 115 // ----------------------------------------------------------------- 116 // Comparison and hashing 117 118 /** 119 * Compares the specified object with this message for equality. Returns 120 * <tt>true</tt> if the given object is a message of the same type (as 121 * defined by {@code getDescriptorForType()}) and has identical values for 122 * all of its fields. 123 * 124 * @param other object to be compared for equality with this message 125 * @return <tt>true</tt> if the specified object is equal to this message 126 */ 127 @Override 128 boolean equals(Object other); 129 130 /** 131 * Returns the hash code value for this message. The hash code of a message 132 * is defined to be <tt>getDescriptor().hashCode() ^ map.hashCode()</tt>, 133 * where <tt>map</tt> is a map of field numbers to field values. 134 * 135 * @return the hash code value for this message 136 * @see Map#hashCode() 137 */ 138 @Override 139 int hashCode(); 140 141 // ----------------------------------------------------------------- 142 // Convenience methods. 143 144 /** 145 * Converts the message to a string in protocol buffer text format. This is 146 * just a trivial wrapper around {@link TextFormat#printToString(Message)}. 147 */ 148 @Override 149 String toString(); 150 151 // ================================================================= 152 // Builders 153 154 // (From MessageLite, re-declared here only for return type covariance.) 155 Builder newBuilderForType(); 156 Builder toBuilder(); 157 158 /** 159 * Abstract interface implemented by Protocol Message builders. 160 */ 161 interface Builder extends MessageLite.Builder { 162 // (From MessageLite.Builder, re-declared here only for return type 163 // covariance.) 164 Builder clear(); 165 166 /** 167 * Merge {@code other} into the message being built. {@code other} must 168 * have the exact same type as {@code this} (i.e. 169 * {@code getDescriptorForType() == other.getDescriptorForType()}). 170 * 171 * Merging occurs as follows. For each field:<br> 172 * * For singular primitive fields, if the field is set in {@code other}, 173 * then {@code other}'s value overwrites the value in this message.<br> 174 * * For singular message fields, if the field is set in {@code other}, 175 * it is merged into the corresponding sub-message of this message 176 * using the same merging rules.<br> 177 * * For repeated fields, the elements in {@code other} are concatenated 178 * with the elements in this message. 179 * 180 * This is equivalent to the {@code Message::MergeFrom} method in C++. 181 */ 182 Builder mergeFrom(Message other); 183 184 // (From MessageLite.Builder, re-declared here only for return type 185 // covariance.) 186 Message build(); 187 Message buildPartial(); 188 Builder clone(); 189 Builder mergeFrom(CodedInputStream input) throws IOException; 190 Builder mergeFrom(CodedInputStream input, 191 ExtensionRegistryLite extensionRegistry) 192 throws IOException; 193 194 /** 195 * Get the message's type's descriptor. 196 * See {@link Message#getDescriptorForType()}. 197 */ 198 Descriptors.Descriptor getDescriptorForType(); 199 200 // (From MessageLite.Builder, re-declared here only for return type 201 // covariance.) 202 Message getDefaultInstanceForType(); 203 204 /** 205 * Like {@link Message#getAllFields()}. The returned map may or may not 206 * reflect future changes to the builder. Either way, the returned map is 207 * itself unmodifiable. 208 */ 209 Map<Descriptors.FieldDescriptor, Object> getAllFields(); 210 211 /** 212 * Create a Builder for messages of the appropriate type for the given 213 * field. Messages built with this can then be passed to setField(), 214 * setRepeatedField(), or addRepeatedField(). 215 */ 216 Builder newBuilderForField(Descriptors.FieldDescriptor field); 217 218 /** Like {@link Message#hasField(Descriptors.FieldDescriptor)} */ 219 boolean hasField(Descriptors.FieldDescriptor field); 220 221 /** Like {@link Message#getField(Descriptors.FieldDescriptor)} */ 222 Object getField(Descriptors.FieldDescriptor field); 223 224 /** 225 * Sets a field to the given value. The value must be of the correct type 226 * for this field, i.e. the same type that 227 * {@link Message#getField(Descriptors.FieldDescriptor)} would return. 228 */ 229 Builder setField(Descriptors.FieldDescriptor field, Object value); 230 231 /** 232 * Clears the field. This is exactly equivalent to calling the generated 233 * "clear" accessor method corresponding to the field. 234 */ 235 Builder clearField(Descriptors.FieldDescriptor field); 236 237 /** 238 * Like {@link Message#getRepeatedFieldCount(Descriptors.FieldDescriptor)} 239 */ 240 int getRepeatedFieldCount(Descriptors.FieldDescriptor field); 241 242 /** 243 * Like {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} 244 */ 245 Object getRepeatedField(Descriptors.FieldDescriptor field, int index); 246 247 /** 248 * Sets an element of a repeated field to the given value. The value must 249 * be of the correct type for this field, i.e. the same type that 250 * {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} would 251 * return. 252 * @throws IllegalArgumentException The field is not a repeated field, or 253 * {@code field.getContainingType() != getDescriptorForType()}. 254 */ 255 Builder setRepeatedField(Descriptors.FieldDescriptor field, 256 int index, Object value); 257 258 /** 259 * Like {@code setRepeatedField}, but appends the value as a new element. 260 * @throws IllegalArgumentException The field is not a repeated field, or 261 * {@code field.getContainingType() != getDescriptorForType()}. 262 */ 263 Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value); 264 265 /** Get the {@link UnknownFieldSet} for this message. */ 266 UnknownFieldSet getUnknownFields(); 267 268 /** Set the {@link UnknownFieldSet} for this message. */ 269 Builder setUnknownFields(UnknownFieldSet unknownFields); 270 271 /** 272 * Merge some unknown fields into the {@link UnknownFieldSet} for this 273 * message. 274 */ 275 Builder mergeUnknownFields(UnknownFieldSet unknownFields); 276 277 // --------------------------------------------------------------- 278 // Convenience methods. 279 280 // (From MessageLite.Builder, re-declared here only for return type 281 // covariance.) 282 Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException; 283 Builder mergeFrom(ByteString data, 284 ExtensionRegistryLite extensionRegistry) 285 throws InvalidProtocolBufferException; 286 Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException; 287 Builder mergeFrom(byte[] data, int off, int len) 288 throws InvalidProtocolBufferException; 289 Builder mergeFrom(byte[] data, 290 ExtensionRegistryLite extensionRegistry) 291 throws InvalidProtocolBufferException; 292 Builder mergeFrom(byte[] data, int off, int len, 293 ExtensionRegistryLite extensionRegistry) 294 throws InvalidProtocolBufferException; 295 Builder mergeFrom(InputStream input) throws IOException; 296 Builder mergeFrom(InputStream input, 297 ExtensionRegistryLite extensionRegistry) 298 throws IOException; 299 boolean mergeDelimitedFrom(InputStream input) 300 throws IOException; 301 boolean mergeDelimitedFrom(InputStream input, 302 ExtensionRegistryLite extensionRegistry) 303 throws IOException; 304 } 305} 306