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 | |
---|
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 | */ |
---|
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 | } |
---|