• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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.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  */
67 public 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    */
writeTo(CodedOutputStream output)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    */
getSerializedSize()80   int getSerializedSize();
81 
82 
83   /**
84    * Gets the parser for a message of the same type as this message.
85    */
getParserForType()86   Parser<? extends MessageLite> getParserForType();
87 
88   // -----------------------------------------------------------------
89   // Convenience methods.
90 
91   /**
92    * Serializes the message to a {@code ByteString} and returns it. This is
93    * just a trivial wrapper around
94    * {@link #writeTo(CodedOutputStream)}.
95    */
toByteString()96   ByteString toByteString();
97 
98   /**
99    * Serializes the message to a {@code byte} array and returns it.  This is
100    * just a trivial wrapper around
101    * {@link #writeTo(CodedOutputStream)}.
102    */
toByteArray()103   byte[] toByteArray();
104 
105   /**
106    * Serializes the message and writes it to {@code output}.  This is just a
107    * trivial wrapper around {@link #writeTo(CodedOutputStream)}.  This does
108    * not flush or close the stream.
109    * <p>
110    * NOTE:  Protocol Buffers are not self-delimiting.  Therefore, if you write
111    * any more data to the stream after the message, you must somehow ensure
112    * that the parser on the receiving end does not interpret this as being
113    * part of the protocol message.  This can be done e.g. by writing the size
114    * of the message before the data, then making sure to limit the input to
115    * that size on the receiving end (e.g. by wrapping the InputStream in one
116    * which limits the input).  Alternatively, just use
117    * {@link #writeDelimitedTo(OutputStream)}.
118    */
writeTo(OutputStream output)119   void writeTo(OutputStream output) throws IOException;
120 
121   /**
122    * Like {@link #writeTo(OutputStream)}, but writes the size of the message
123    * as a varint before writing the data.  This allows more data to be written
124    * to the stream after the message without the need to delimit the message
125    * data yourself.  Use {@link Builder#mergeDelimitedFrom(InputStream)} (or
126    * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)})
127    * to parse messages written by this method.
128    */
writeDelimitedTo(OutputStream output)129   void writeDelimitedTo(OutputStream output) throws IOException;
130 
131 
132   // =================================================================
133   // Builders
134 
135   /**
136    * Constructs a new builder for a message of the same type as this message.
137    */
newBuilderForType()138   Builder newBuilderForType();
139 
140   /**
141    * Constructs a builder initialized with the current message.  Use this to
142    * derive a new message from the current one.
143    */
toBuilder()144   Builder toBuilder();
145 
146   /**
147    * Abstract interface implemented by Protocol Message builders.
148    */
149   interface Builder extends MessageLiteOrBuilder, Cloneable {
150     /** Resets all fields to their default values. */
clear()151     Builder clear();
152 
153     /**
154      * Constructs the message based on the state of the Builder. Subsequent
155      * changes to the Builder will not affect the returned message.
156      * @throws UninitializedMessageException The message is missing one or more
157      *         required fields (i.e. {@link #isInitialized()} returns false).
158      *         Use {@link #buildPartial()} to bypass this check.
159      */
build()160     MessageLite build();
161 
162     /**
163      * Like {@link #build()}, but does not throw an exception if the message
164      * is missing required fields.  Instead, a partial message is returned.
165      * Subsequent changes to the Builder will not affect the returned message.
166      */
buildPartial()167     MessageLite buildPartial();
168 
169     /**
170      * Clones the Builder.
171      * @see Object#clone()
172      */
clone()173     Builder clone();
174 
175     /**
176      * Parses a message of this type from the input and merges it with this
177      * message.
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>Use {@code buildPartial()} to build, which ignores missing
188      *       required fields.
189      * </ul>
190      *
191      * <p>Note:  The caller should call
192      * {@link CodedInputStream#checkLastTagWas(int)} after calling this to
193      * verify that the last tag seen was the appropriate end-group tag,
194      * or zero for EOF.
195      */
mergeFrom(CodedInputStream input)196     Builder mergeFrom(CodedInputStream input) throws IOException;
197 
198     /**
199      * Like {@link Builder#mergeFrom(CodedInputStream)}, but also
200      * parses extensions.  The extensions that you want to be able to parse
201      * must be registered in {@code extensionRegistry}.  Extensions not in
202      * the registry will be treated as unknown fields.
203      */
mergeFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry)204     Builder mergeFrom(CodedInputStream input,
205                       ExtensionRegistryLite extensionRegistry)
206                       throws IOException;
207 
208     // ---------------------------------------------------------------
209     // Convenience methods.
210 
211     /**
212      * Parse {@code data} as a message of this type and merge it with the
213      * message being built.  This is just a small wrapper around
214      * {@link #mergeFrom(CodedInputStream)}.
215      *
216      * @return this
217      */
mergeFrom(ByteString data)218     Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException;
219 
220     /**
221      * Parse {@code data} as a message of this type and merge it with the
222      * message being built.  This is just a small wrapper around
223      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
224      *
225      * @return this
226      */
mergeFrom(ByteString data, ExtensionRegistryLite extensionRegistry)227     Builder mergeFrom(ByteString data,
228                       ExtensionRegistryLite extensionRegistry)
229                       throws InvalidProtocolBufferException;
230 
231     /**
232      * Parse {@code data} as a message of this type and merge it with the
233      * message being built.  This is just a small wrapper around
234      * {@link #mergeFrom(CodedInputStream)}.
235      *
236      * @return this
237      */
mergeFrom(byte[] data)238     Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException;
239 
240     /**
241      * Parse {@code data} as a message of this type and merge it with the
242      * message being built.  This is just a small wrapper around
243      * {@link #mergeFrom(CodedInputStream)}.
244      *
245      * @return this
246      */
mergeFrom(byte[] data, int off, int len)247     Builder mergeFrom(byte[] data, int off, int len)
248                       throws InvalidProtocolBufferException;
249 
250     /**
251      * Parse {@code data} as a message of this type and merge it with the
252      * message being built.  This is just a small wrapper around
253      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
254      *
255      * @return this
256      */
mergeFrom(byte[] data, ExtensionRegistryLite extensionRegistry)257     Builder mergeFrom(byte[] data,
258                       ExtensionRegistryLite extensionRegistry)
259                       throws InvalidProtocolBufferException;
260 
261     /**
262      * Parse {@code data} as a message of this type and merge it with the
263      * message being built.  This is just a small wrapper around
264      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
265      *
266      * @return this
267      */
mergeFrom(byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry)268     Builder mergeFrom(byte[] data, int off, int len,
269                       ExtensionRegistryLite extensionRegistry)
270                       throws InvalidProtocolBufferException;
271 
272     /**
273      * Parse a message of this type from {@code input} and merge it with the
274      * message being built.  This is just a small wrapper around
275      * {@link #mergeFrom(CodedInputStream)}.  Note that this method always
276      * reads the <i>entire</i> input (unless it throws an exception).  If you
277      * want it to stop earlier, you will need to wrap your input in some
278      * wrapper stream that limits reading.  Or, use
279      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write your message
280      * and {@link #mergeDelimitedFrom(InputStream)} to read it.
281      * <p>
282      * Despite usually reading the entire input, this does not close the stream.
283      *
284      * @return this
285      */
mergeFrom(InputStream input)286     Builder mergeFrom(InputStream input) throws IOException;
287 
288     /**
289      * Parse a message of this type from {@code input} and merge it with the
290      * message being built.  This is just a small wrapper around
291      * {@link #mergeFrom(CodedInputStream,ExtensionRegistryLite)}.
292      *
293      * @return this
294      */
mergeFrom(InputStream input, ExtensionRegistryLite extensionRegistry)295     Builder mergeFrom(InputStream input,
296                       ExtensionRegistryLite extensionRegistry)
297                       throws IOException;
298 
299     /**
300      * Merge {@code other} into the message being built.  {@code other} must
301      * have the exact same type as {@code this} (i.e.
302      * {@code getClass().equals(getDefaultInstanceForType().getClass())}).
303      *
304      * Merging occurs as follows.  For each field:<br>
305      * * For singular primitive fields, if the field is set in {@code other},
306      *   then {@code other}'s value overwrites the value in this message.<br>
307      * * For singular message fields, if the field is set in {@code other},
308      *   it is merged into the corresponding sub-message of this message
309      *   using the same merging rules.<br>
310      * * For repeated fields, the elements in {@code other} are concatenated
311      *   with the elements in this message.
312      * * For oneof groups, if the other message has one of the fields set,
313      *   the group of this message is cleared and replaced by the field
314      *   of the other message, so that the oneof constraint is preserved.
315      *
316      * This is equivalent to the {@code Message::MergeFrom} method in C++.
317      */
mergeFrom(MessageLite other)318     Builder mergeFrom(MessageLite other);
319 
320     /**
321      * Like {@link #mergeFrom(InputStream)}, but does not read until EOF.
322      * Instead, the size of the message (encoded as a varint) is read first,
323      * then the message data.  Use
324      * {@link MessageLite#writeDelimitedTo(OutputStream)} to write messages in
325      * this format.
326      *
327      * @return True if successful, or false if the stream is at EOF when the
328      *         method starts.  Any other error (including reaching EOF during
329      *         parsing) will cause an exception to be thrown.
330      */
mergeDelimitedFrom(InputStream input)331     boolean mergeDelimitedFrom(InputStream input)
332                                throws IOException;
333 
334     /**
335      * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions.
336      */
mergeDelimitedFrom(InputStream input, ExtensionRegistryLite extensionRegistry)337     boolean mergeDelimitedFrom(InputStream input,
338                                ExtensionRegistryLite extensionRegistry)
339                                throws IOException;
340   }
341 }
342