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