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