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