← Back to branch summary

~statik/ubuntu/maverick/protobuf/A

« back to all changes in this revision

Viewing changes to java/src/main/java/com/google/protobuf/Message.java

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2010-02-11 11:13:19 UTC
  • mfrom: (2.2.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20100211111319-zdn8hmw0gh8s4cf8
Tags: 2.2.0a-0.1ubuntu1
* Merge from Debian testing.
* Remaining Ubuntu changes:
  - Don't use python2.4.
* Ubuntu changes dropped:
  - Disable death tests on Itanium, fixed upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
java/src/main/java/com/google/protobuf/Message.java
33
33
 
34
34
package com.google.protobuf;
35
35
 
 
36
import java.io.IOException;
36
37
import java.io.InputStream;
37
 
import java.io.IOException;
38
 
import java.io.OutputStream;
39
38
import java.util.Map;
40
39
 
41
40
/**
42
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.
43
48
 *
44
49
 * @author kenton@google.com Kenton Varda
45
50
 */
46
 
public interface Message {
 
51
public interface Message extends MessageLite {
47
52
  /**
48
53
   * Get the message's type's descriptor.  This differs from the
49
54
   * {@code getDescriptor()} method of generated message classes in that
53
58
   */
54
59
  Descriptors.Descriptor getDescriptorForType();
55
60
 
56
 
  /**
57
 
   * Get an instance of the type with all fields set to their default values.
58
 
   * This may or may not be a singleton.  This differs from the
59
 
   * {@code getDefaultInstance()} method of generated message classes in that
60
 
   * this method is an abstract method of the {@code Message} interface
61
 
   * whereas {@code getDefaultInstance()} is a static method of a specific
62
 
   * class.  They return the same thing.
63
 
   */
 
61
  // (From MessageLite, re-declared here only for return type covariance.)
64
62
  Message getDefaultInstanceForType();
65
63
 
66
64
  /**
114
112
  /** Get the {@link UnknownFieldSet} for this message. */
115
113
  UnknownFieldSet getUnknownFields();
116
114
 
117
 
  /**
118
 
   * Returns true if all required fields in the message and all embedded
119
 
   * messages are set, false otherwise.
120
 
   */
121
 
  boolean isInitialized();
122
 
 
123
 
  /**
124
 
   * Serializes the message and writes it to {@code output}.  This does not
125
 
   * flush or close the stream.
126
 
   */
127
 
  void writeTo(CodedOutputStream output) throws IOException;
128
 
 
129
 
  /**
130
 
   * Get the number of bytes required to encode this message.  The result
131
 
   * is only computed on the first call and memoized after that.
132
 
   */
133
 
  int getSerializedSize();
134
 
 
135
115
  // -----------------------------------------------------------------
136
116
  // Comparison and hashing
137
117
 
144
124
   * @param other object to be compared for equality with this message
145
125
   * @return <tt>true</tt> if the specified object is equal to this message
146
126
   */
 
127
  @Override
147
128
  boolean equals(Object other);
148
129
 
149
130
  /**
154
135
   * @return the hash code value for this message
155
136
   * @see Map#hashCode()
156
137
   */
 
138
  @Override
157
139
  int hashCode();
158
140
 
159
141
  // -----------------------------------------------------------------
163
145
   * Converts the message to a string in protocol buffer text format. This is
164
146
   * just a trivial wrapper around {@link TextFormat#printToString(Message)}.
165
147
   */
 
148
  @Override
166
149
  String toString();
167
150
 
168
 
  /**
169
 
   * Serializes the message to a {@code ByteString} and returns it. This is
170
 
   * just a trivial wrapper around
171
 
   * {@link #writeTo(CodedOutputStream)}.
172
 
   */
173
 
  ByteString toByteString();
174
 
 
175
 
  /**
176
 
   * Serializes the message to a {@code byte} array and returns it.  This is
177
 
   * just a trivial wrapper around
178
 
   * {@link #writeTo(CodedOutputStream)}.
179
 
   */
180
 
  byte[] toByteArray();
181
 
 
182
 
  /**
183
 
   * Serializes the message and writes it to {@code output}.  This is just a
184
 
   * trivial wrapper around {@link #writeTo(CodedOutputStream)}.  This does
185
 
   * not flush or close the stream.
186
 
   * <p>
187
 
   * NOTE:  Protocol Buffers are not self-delimiting.  Therefore, if you write
188
 
   * any more data to the stream after the message, you must somehow ensure
189
 
   * that the parser on the receiving end does not interpret this as being
190
 
   * part of the protocol message.  This can be done e.g. by writing the size
191
 
   * of the message before the data, then making sure to limit the input to
192
 
   * that size on the receiving end (e.g. by wrapping the InputStream in one
193
 
   * which limits the input).  Alternatively, just use
194
 
   * {@link #writeDelimitedTo(OutputStream)}.
195
 
   */
196
 
  void writeTo(OutputStream output) throws IOException;
197
 
 
198
 
  /**
199
 
   * Like {@link #writeTo(OutputStream)}, but writes the size of the message
200
 
   * as a varint before writing the data.  This allows more data to be written
201
 
   * to the stream after the message without the need to delimit the message
202
 
   * data yourself.  Use {@link Builder#mergeDelimitedFrom(InputStream)} (or
203
 
   * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)})
204
 
   * to parse messages written by this method.
205
 
   */
206
 
  void writeDelimitedTo(OutputStream output) throws IOException;
207
 
 
208
151
  // =================================================================
209
152
  // Builders
210
153
 
211
 
  /**
212
 
   * Constructs a new builder for a message of the same type as this message.
213
 
   */
 
154
  // (From MessageLite, re-declared here only for return type covariance.)
214
155
  Builder newBuilderForType();
215
 
 
216
 
  /**
217
 
   * Constructs a builder initialized with the current message.  Use this to
218
 
   * derive a new message from the current one.
219
 
   */
220
156
  Builder toBuilder();
221
157
 
222
158
  /**
223
159
   * Abstract interface implemented by Protocol Message builders.
224
160
   */
225
 
  public static interface Builder extends Cloneable {
226
 
    /** Resets all fields to their default values. */
 
161
  interface Builder extends MessageLite.Builder {
 
162
    // (From MessageLite.Builder, re-declared here only for return type
 
163
    // covariance.)
227
164
    Builder clear();
228
165
 
229
166
    /**
244
181
     */
245
182
    Builder mergeFrom(Message other);
246
183
 
247
 
    /**
248
 
     * Construct the final message.  Once this is called, the Builder is no
249
 
     * longer valid, and calling any other method may throw a
250
 
     * NullPointerException.  If you need to continue working with the builder
251
 
     * after calling {@code build()}, {@code clone()} it first.
252
 
     * @throws UninitializedMessageException The message is missing one or more
253
 
     *         required fields (i.e. {@link #isInitialized()} returns false).
254
 
     *         Use {@link #buildPartial()} to bypass this check.
255
 
     */
 
184
    // (From MessageLite.Builder, re-declared here only for return type
 
185
    // covariance.)
256
186
    Message build();
257
 
 
258
 
    /**
259
 
     * Like {@link #build()}, but does not throw an exception if the message
260
 
     * is missing required fields.  Instead, a partial message is returned.
261
 
     */
262
187
    Message buildPartial();
263
 
 
264
 
    /**
265
 
     * Clones the Builder.
266
 
     * @see Object#clone()
267
 
     */
268
188
    Builder clone();
269
 
 
270
 
    /**
271
 
     * Returns true if all required fields in the message and all embedded
272
 
     * messages are set, false otherwise.
273
 
     */
274
 
    boolean isInitialized();
275
 
 
276
 
    /**
277
 
     * Parses a message of this type from the input and merges it with this
278
 
     * message, as if using {@link Builder#mergeFrom(Message)}.
279
 
     *
280
 
     * <p>Warning:  This does not verify that all required fields are present in
281
 
     * the input message.  If you call {@link #build()} without setting all
282
 
     * required fields, it will throw an {@link UninitializedMessageException},
283
 
     * which is a {@code RuntimeException} and thus might not be caught.  There
284
 
     * are a few good ways to deal with this:
285
 
     * <ul>
286
 
     *   <li>Call {@link #isInitialized()} to verify that all required fields
287
 
     *       are set before building.
288
 
     *   <li>Parse the message separately using one of the static
289
 
     *       {@code parseFrom} methods, then use {@link #mergeFrom(Message)}
290
 
     *       to merge it with this one.  {@code parseFrom} will throw an
291
 
     *       {@link InvalidProtocolBufferException} (an {@code IOException})
292
 
     *       if some required fields are missing.
293
 
     *   <li>Use {@code buildPartial()} to build, which ignores missing
294
 
     *       required fields.
295
 
     * </ul>
296
 
     *
297
 
     * <p>Note:  The caller should call
298
 
     * {@link CodedInputStream#checkLastTagWas(int)} after calling this to
299
 
     * verify that the last tag seen was the appropriate end-group tag,
300
 
     * or zero for EOF.
301
 
     */
302
189
    Builder mergeFrom(CodedInputStream input) throws IOException;
303
 
 
304
 
    /**
305
 
     * Like {@link Builder#mergeFrom(CodedInputStream)}, but also
306
 
     * parses extensions.  The extensions that you want to be able to parse
307
 
     * must be registered in {@code extensionRegistry}.  Extensions not in
308
 
     * the registry will be treated as unknown fields.
309
 
     */
310
190
    Builder mergeFrom(CodedInputStream input,
311
 
                      ExtensionRegistry extensionRegistry)
 
191
                      ExtensionRegistryLite extensionRegistry)
312
192
                      throws IOException;
313
193
 
314
194
    /**
317
197
     */
318
198
    Descriptors.Descriptor getDescriptorForType();
319
199
 
320
 
    /**
321
 
     * Get the message's type's default instance.
322
 
     * See {@link Message#getDefaultInstanceForType()}.
323
 
     */
 
200
    // (From MessageLite.Builder, re-declared here only for return type
 
201
    // covariance.)
324
202
    Message getDefaultInstanceForType();
325
203
 
326
204
    /**
399
277
    // ---------------------------------------------------------------
400
278
    // Convenience methods.
401
279
 
402
 
    /**
403
 
     * Parse {@code data} as a message of this type and merge it with the
404
 
     * message being built.  This is just a small wrapper around
405
 
     * {@link #mergeFrom(CodedInputStream)}.
406
 
     */
 
280
    // (From MessageLite.Builder, re-declared here only for return type
 
281
    // covariance.)
407
282
    Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
408
 
 
409
 
    /**
410
 
     * Parse {@code data} as a message of this type and merge it with the
411
 
     * message being built.  This is just a small wrapper around
412
 
     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
413
 
     */
414
283
    Builder mergeFrom(ByteString data,
415
 
                      ExtensionRegistry extensionRegistry)
416
 
                      throws InvalidProtocolBufferException;
417
 
 
418
 
    /**
419
 
     * Parse {@code data} as a message of this type and merge it with the
420
 
     * message being built.  This is just a small wrapper around
421
 
     * {@link #mergeFrom(CodedInputStream)}.
422
 
     */
423
 
    public Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
424
 
 
425
 
    /**
426
 
     * Parse {@code data} as a message of this type and merge it with the
427
 
     * message being built.  This is just a small wrapper around
428
 
     * {@link #mergeFrom(CodedInputStream)}.
429
 
     */
430
 
    public Builder mergeFrom(byte[] data, int off, int len) throws InvalidProtocolBufferException;
431
 
 
432
 
    /**
433
 
     * Parse {@code data} as a message of this type and merge it with the
434
 
     * message being built.  This is just a small wrapper around
435
 
     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
436
 
     */
 
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;
437
289
    Builder mergeFrom(byte[] data,
438
 
                      ExtensionRegistry extensionRegistry)
 
290
                      ExtensionRegistryLite extensionRegistry)
439
291
                      throws InvalidProtocolBufferException;
440
 
 
441
 
    /**
442
 
     * Parse {@code data} as a message of this type and merge it with the
443
 
     * message being built.  This is just a small wrapper around
444
 
     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
445
 
     */
446
292
    Builder mergeFrom(byte[] data, int off, int len,
447
 
                      ExtensionRegistry extensionRegistry)
 
293
                      ExtensionRegistryLite extensionRegistry)
448
294
                      throws InvalidProtocolBufferException;
449
 
 
450
 
    /**
451
 
     * Parse a message of this type from {@code input} and merge it with the
452
 
     * message being built.  This is just a small wrapper around
453
 
     * {@link #mergeFrom(CodedInputStream)}.  Note that this method always
454
 
     * reads the <i>entire</i> input (unless it throws an exception).  If you
455
 
     * want it to stop earlier, you will need to wrap your input in some
456
 
     * wrapper stream that limits reading.  Or, use
457
 
     * {@link Message#writeDelimitedTo(OutputStream)} to write your message and
458
 
     * {@link #mergeDelimitedFrom(InputStream)} to read it.
459
 
     * <p>
460
 
     * Despite usually reading the entire input, this does not close the stream.
461
 
     */
462
295
    Builder mergeFrom(InputStream input) throws IOException;
463
 
 
464
 
    /**
465
 
     * Parse a message of this type from {@code input} and merge it with the
466
 
     * message being built.  This is just a small wrapper around
467
 
     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
468
 
     */
469
296
    Builder mergeFrom(InputStream input,
470
 
                      ExtensionRegistry extensionRegistry)
 
297
                      ExtensionRegistryLite extensionRegistry)
471
298
                      throws IOException;
472
 
 
473
 
    /**
474
 
     * Like {@link #mergeFrom(InputStream)}, but does not read until EOF.
475
 
     * Instead, the size of the message (encoded as a varint) is read first,
476
 
     * then the message data.  Use
477
 
     * {@link Message#writeDelimitedTo(OutputStream)} to write messages in this
478
 
     * format.
479
 
     */
480
299
    Builder mergeDelimitedFrom(InputStream input)
481
300
                               throws IOException;
482
 
 
483
 
    /**
484
 
     * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions.
485
 
     */
486
301
    Builder mergeDelimitedFrom(InputStream input,
487
 
                               ExtensionRegistry extensionRegistry)
 
302
                               ExtensionRegistryLite extensionRegistry)
488
303
                               throws IOException;
489
304
  }
490
305
}