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 package com.google.protobuf.micro;
32 
33 import com.google.protobuf.micro.CodedOutputStreamMicro;
34 import java.io.IOException;
35 
36 /**
37  * Abstract interface implemented by Protocol Message objects.
38  *
39  * @author wink@google.com Wink Saville
40  */
41 public abstract class MessageMicro {
42     /**
43      * Get the number of bytes required to encode this message.
44      * Returns the cached size or calls getSerializedSize which
45      * sets the cached size. This is used internally when serializing
46      * so the size is only computed once. If a member is modified
47      * then this could be stale call getSerializedSize if in doubt.
48      */
49     abstract public int getCachedSize();
50 
51     /**
52      * Computes the number of bytes required to encode this message.
53      * The size is cached and the cached result can be retrieved
54      * using getCachedSize().
55      */
56     abstract public int getSerializedSize();
57 
58     /**
59      * Serializes the message and writes it to {@code output}.  This does not
60      * flush or close the stream.
61      */
62     abstract public void writeTo(CodedOutputStreamMicro output) throws java.io.IOException;
63 
64     /**
65      * Parse {@code input} as a message of this type and merge it with the
66      * message being built.
67      */
68     abstract public MessageMicro mergeFrom(final CodedInputStreamMicro input) throws IOException;
69 
70     /**
71      * Serialize to a byte array.
72      * @return byte array with the serialized data.
73      */
74     public byte[] toByteArray() {
75         final byte[] result = new byte[getSerializedSize()];
76         toByteArray(result, 0, result.length);
77         return result;
78     }
79 
80     /**
81      * Serialize to a byte array starting at offset through length. The
82      * method getSerializedSize must have been called prior to calling
83      * this method so the proper length is know.  If an attempt to
84      * write more than length bytes OutOfSpaceException will be thrown
85      * and if length bytes are not written then IllegalStateException
86      * is thrown.
87      * @return byte array with the serialized data.
88      */
89     public void toByteArray(byte [] data, int offset, int length) {
90         try {
91             final CodedOutputStreamMicro output = CodedOutputStreamMicro.newInstance(data, offset, length);
92             writeTo(output);
93             output.checkNoSpaceLeft();
94         } catch (IOException e) {
95             throw new RuntimeException("Serializing to a byte array threw an IOException "
96                     + "(should never happen).");
97         }
98     }
99 
100     /**
101      * Parse {@code data} as a message of this type and merge it with the
102      * message being built.
103      */
104     public MessageMicro mergeFrom(final byte[] data) throws InvalidProtocolBufferMicroException {
105         return mergeFrom(data, 0, data.length);
106     }
107 
108     /**
109      * Parse {@code data} as a message of this type and merge it with the
110      * message being built.
111      */
112     public MessageMicro mergeFrom(final byte[] data, final int off, final int len)
113             throws InvalidProtocolBufferMicroException {
114         try {
115             final CodedInputStreamMicro input = CodedInputStreamMicro.newInstance(data, off, len);
116             mergeFrom(input);
117             input.checkLastTagWas(0);
118             return this;
119         } catch (InvalidProtocolBufferMicroException e) {
120             throw e;
121         } catch (IOException e) {
122             throw new RuntimeException("Reading from a byte array threw an IOException (should "
123                     + "never happen).");
124         }
125     }
126 
127     /**
128      * Called by subclasses to parse an unknown field.
129      * @return {@code true} unless the tag is an end-group tag.
130      */
131     protected boolean parseUnknownField(
132         final CodedInputStreamMicro input,
133         final int tag) throws IOException {
134       return input.skipField(tag);
135     }
136 }
137