PageRenderTime 41ms CodeModel.GetById 14ms app.highlight 16ms RepoModel.GetById 2ms app.codeStats 0ms

/thirdparty/breakpad/third_party/protobuf/protobuf/java/src/main/java/com/google/protobuf/MessageLite.java

http://github.com/tomahawk-player/tomahawk
Java | 325 lines | 46 code | 32 blank | 247 comment | 0 complexity | 5b9db0bd004c9a00e4ef9b224a2fff34 MD5 | raw file
  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.io.OutputStream;
 39
 40/**
 41 * Abstract interface implemented by Protocol Message objects.
 42 *
 43 * <p>This interface is implemented by all protocol message objects.  Non-lite
 44 * messages additionally implement the Message interface, which is a subclass
 45 * of MessageLite.  Use MessageLite instead when you only need the subset of
 46 * features which it supports -- namely, nothing that uses descriptors or
 47 * reflection.  You can instruct the protocol compiler to generate classes
 48 * which implement only MessageLite, not the full Message interface, by adding
 49 * the follow line to the .proto file:
 50 * <pre>
 51 *   option optimize_for = LITE_RUNTIME;
 52 * </pre>
 53 *
 54 * <p>This is particularly useful on resource-constrained systems where the
 55 * full protocol buffers runtime library is too big.
 56 *
 57 * <p>Note that on non-constrained systems (e.g. servers) when you need to link
 58 * in lots of protocol definitions, a better way to reduce total code footprint
 59 * is to use {@code optimize_for = CODE_SIZE}.  This will make the generated
 60 * code smaller while still supporting all the same features (at the expense of
 61 * speed).  {@code optimize_for = LITE_RUNTIME} is best when you only have a
 62 * small number of message types linked into your binary, in which case the
 63 * size of the protocol buffers runtime itself is the biggest problem.
 64 *
 65 * @author kenton@google.com Kenton Varda
 66 */
 67public interface MessageLite extends MessageLiteOrBuilder {
 68
 69
 70  /**
 71   * Serializes the message and writes it to {@code output}.  This does not
 72   * flush or close the stream.
 73   */
 74  void writeTo(CodedOutputStream output) throws IOException;
 75
 76  /**
 77   * Get the number of bytes required to encode this message.  The result
 78   * is only computed on the first call and memoized after that.
 79   */
 80  int getSerializedSize();
 81
 82  // -----------------------------------------------------------------
 83  // Convenience methods.
 84
 85  /**
 86   * Serializes the message to a {@code ByteString} and returns it. This is
 87   * just a trivial wrapper around
 88   * {@link #writeTo(CodedOutputStream)}.
 89   */
 90  ByteString toByteString();
 91
 92  /**
 93   * Serializes the message to a {@code byte} array and returns it.  This is
 94   * just a trivial wrapper around
 95   * {@link #writeTo(CodedOutputStream)}.
 96   */
 97  byte[] toByteArray();
 98
 99  /**
100   * Serializes the message and writes it to {@code output}.  This is just a
101   * trivial wrapper around {@link #writeTo(CodedOutputStream)}.  This does
102   * not flush or close the stream.
103   * <p>
104   * NOTE:  Protocol Buffers are not self-delimiting.  Therefore, if you write
105   * any more data to the stream after the message, you must somehow ensure
106   * that the parser on the receiving end does not interpret this as being
107   * part of the protocol message.  This can be done e.g. by writing the size
108   * of the message before the data, then making sure to limit the input to
109   * that size on the receiving end (e.g. by wrapping the InputStream in one
110   * which limits the input).  Alternatively, just use
111   * {@link #writeDelimitedTo(OutputStream)}.
112   */
113  void writeTo(OutputStream output) throws IOException;
114
115  /**
116   * Like {@link #writeTo(OutputStream)}, but writes the size of the message
117   * as a varint before writing the data.  This allows more data to be written
118   * to the stream after the message without the need to delimit the message
119   * data yourself.  Use {@link Builder#mergeDelimitedFrom(InputStream)} (or
120   * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)})
121   * to parse messages written by this method.
122   */
123  void writeDelimitedTo(OutputStream output) throws IOException;
124
125  // =================================================================
126  // Builders
127
128  /**
129   * Constructs a new builder for a message of the same type as this message.
130   */
131  Builder newBuilderForType();
132
133  /**
134   * Constructs a builder initialized with the current message.  Use this to
135   * derive a new message from the current one.
136   */
137  Builder toBuilder();
138
139  /**
140   * Abstract interface implemented by Protocol Message builders.
141   */
142  interface Builder extends MessageLiteOrBuilder, Cloneable {
143    /** Resets all fields to their default values. */
144    Builder clear();
145
146    /**
147     * Construct the final message.  Once this is called, the Builder is no
148     * longer valid, and calling any other method will result in undefined
149     * behavior and may throw a NullPointerException.  If you need to continue
150     * working with the builder after calling {@code build()}, {@code clone()}
151     * it first.
152     * @throws UninitializedMessageException The message is missing one or more
153     *         required fields (i.e. {@link #isInitialized()} returns false).
154     *         Use {@link #buildPartial()} to bypass this check.
155     */
156    MessageLite build();
157
158    /**
159     * Like {@link #build()}, but does not throw an exception if the message
160     * is missing required fields.  Instead, a partial message is returned.
161     * Once this is called, the Builder is no longer valid, and calling any
162     * will result in undefined behavior and may throw a NullPointerException.
163     *
164     * If you need to continue working with the builder after calling
165     * {@code buildPartial()}, {@code clone()} it first.
166     */
167    MessageLite buildPartial();
168
169    /**
170     * Clones the Builder.
171     * @see Object#clone()
172     */
173    Builder clone();
174
175    /**
176     * Parses a message of this type from the input and merges it with this
177     * message, as if using {@link Builder#mergeFrom(MessageLite)}.
178     *
179     * <p>Warning:  This does not verify that all required fields are present in
180     * the input message.  If you call {@link #build()} without setting all
181     * required fields, it will throw an {@link UninitializedMessageException},
182     * which is a {@code RuntimeException} and thus might not be caught.  There
183     * are a few good ways to deal with this:
184     * <ul>
185     *   <li>Call {@link #isInitialized()} to verify that all required fields
186     *       are set before building.
187     *   <li>Parse the message separately using one of the static
188     *       {@code parseFrom} methods, then use {@link #mergeFrom(MessageLite)}
189     *       to merge it with this one.  {@code parseFrom} will throw an
190     *       {@link InvalidProtocolBufferException} (an {@code IOException})
191     *       if some required fields are missing.
192     *   <li>Use {@code buildPartial()} to build, which ignores missing
193     *       required fields.
194     * </ul>
195     *
196     * <p>Note:  The caller should call
197     * {@link CodedInputStream#checkLastTagWas(int)} after calling this to
198     * verify that the last tag seen was the appropriate end-group tag,
199     * or zero for EOF.
200     */
201    Builder mergeFrom(CodedInputStream input) throws IOException;
202
203    /**
204     * Like {@link Builder#mergeFrom(CodedInputStream)}, but also
205     * parses extensions.  The extensions that you want to be able to parse
206     * must be registered in {@code extensionRegistry}.  Extensions not in
207     * the registry will be treated as unknown fields.
208     */
209    Builder mergeFrom(CodedInputStream input,
210                      ExtensionRegistryLite extensionRegistry)
211                      throws IOException;
212
213    // ---------------------------------------------------------------
214    // Convenience methods.
215
216    /**
217     * Parse {@code data} as a message of this type and merge it with the
218     * message being built.  This is just a small wrapper around
219     * {@link #mergeFrom(CodedInputStream)}.
220     *
221     * @return this
222     */
223    Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
224
225    /**
226     * Parse {@code data} as a message of this type and merge it with the
227     * message being built.  This is just a small wrapper around
228     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
229     *
230     * @return this
231     */
232    Builder mergeFrom(ByteString data,
233                      ExtensionRegistryLite extensionRegistry)
234                      throws InvalidProtocolBufferException;
235
236    /**
237     * Parse {@code data} as a message of this type and merge it with the
238     * message being built.  This is just a small wrapper around
239     * {@link #mergeFrom(CodedInputStream)}.
240     *
241     * @return this
242     */
243    Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
244
245    /**
246     * Parse {@code data} as a message of this type and merge it with the
247     * message being built.  This is just a small wrapper around
248     * {@link #mergeFrom(CodedInputStream)}.
249     *
250     * @return this
251     */
252    Builder mergeFrom(byte[] data, int off, int len)
253                      throws InvalidProtocolBufferException;
254
255    /**
256     * Parse {@code data} as a message of this type and merge it with the
257     * message being built.  This is just a small wrapper around
258     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
259     *
260     * @return this
261     */
262    Builder mergeFrom(byte[] data,
263                      ExtensionRegistryLite extensionRegistry)
264                      throws InvalidProtocolBufferException;
265
266    /**
267     * Parse {@code data} as a message of this type and merge it with the
268     * message being built.  This is just a small wrapper around
269     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
270     *
271     * @return this
272     */
273    Builder mergeFrom(byte[] data, int off, int len,
274                      ExtensionRegistryLite extensionRegistry)
275                      throws InvalidProtocolBufferException;
276
277    /**
278     * Parse a message of this type from {@code input} and merge it with the
279     * message being built.  This is just a small wrapper around
280     * {@link #mergeFrom(CodedInputStream)}.  Note that this method always
281     * reads the <i>entire</i> input (unless it throws an exception).  If you
282     * want it to stop earlier, you will need to wrap your input in some
283     * wrapper stream that limits reading.  Or, use
284     * {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message
285     * and {@link #mergeDelimitedFrom(InputStream)} to read it.
286     * <p>
287     * Despite usually reading the entire input, this does not close the stream.
288     *
289     * @return this
290     */
291    Builder mergeFrom(InputStream input) throws IOException;
292
293    /**
294     * Parse a message of this type from {@code input} and merge it with the
295     * message being built.  This is just a small wrapper around
296     * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}.
297     *
298     * @return this
299     */
300    Builder mergeFrom(InputStream input,
301                      ExtensionRegistryLite extensionRegistry)
302                      throws IOException;
303
304    /**
305     * Like {@link #mergeFrom(InputStream)}, but does not read until EOF.
306     * Instead, the size of the message (encoded as a varint) is read first,
307     * then the message data.  Use
308     * {@link MessageLite#writeDelimitedTo(OutputStream)} to write messages in
309     * this format.
310     *
311     * @returns True if successful, or false if the stream is at EOF when the
312     *          method starts.  Any other error (including reaching EOF during
313     *          parsing) will cause an exception to be thrown.
314     */
315    boolean mergeDelimitedFrom(InputStream input)
316                               throws IOException;
317
318    /**
319     * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions.
320     */
321    boolean mergeDelimitedFrom(InputStream input,
322                               ExtensionRegistryLite extensionRegistry)
323                               throws IOException;
324  }
325}