diff options
Diffstat (limited to 'java/src/main/java/com/google/protobuf/Message.java')
| -rw-r--r-- | java/src/main/java/com/google/protobuf/Message.java | 247 |
1 files changed, 31 insertions, 216 deletions
diff --git a/java/src/main/java/com/google/protobuf/Message.java b/java/src/main/java/com/google/protobuf/Message.java index a5951232..c11abdc5 100644 --- a/java/src/main/java/com/google/protobuf/Message.java +++ b/java/src/main/java/com/google/protobuf/Message.java @@ -33,17 +33,22 @@ package com.google.protobuf; -import java.io.InputStream; import java.io.IOException; -import java.io.OutputStream; +import java.io.InputStream; import java.util.Map; /** * Abstract interface implemented by Protocol Message objects. + * <p> + * See also {@link MessageLite}, which defines most of the methods that typical + * users care about. {@link Message} adds to it methods that are not available + * in the "lite" runtime. The biggest added features are introspection and + * reflection -- i.e., getting descriptors for the message type and accessing + * the field values dynamically. * * @author kenton@google.com Kenton Varda */ -public interface Message { +public interface Message extends MessageLite { /** * Get the message's type's descriptor. This differs from the * {@code getDescriptor()} method of generated message classes in that @@ -53,14 +58,7 @@ public interface Message { */ Descriptors.Descriptor getDescriptorForType(); - /** - * Get an instance of the type with all fields set to their default values. - * This may or may not be a singleton. This differs from the - * {@code getDefaultInstance()} method of generated message classes in that - * this method is an abstract method of the {@code Message} interface - * whereas {@code getDefaultInstance()} is a static method of a specific - * class. They return the same thing. - */ + // (From MessageLite, re-declared here only for return type covariance.) Message getDefaultInstanceForType(); /** @@ -114,24 +112,6 @@ public interface Message { /** Get the {@link UnknownFieldSet} for this message. */ UnknownFieldSet getUnknownFields(); - /** - * Returns true if all required fields in the message and all embedded - * messages are set, false otherwise. - */ - boolean isInitialized(); - - /** - * Serializes the message and writes it to {@code output}. This does not - * flush or close the stream. - */ - void writeTo(CodedOutputStream output) throws IOException; - - /** - * Get the number of bytes required to encode this message. The result - * is only computed on the first call and memoized after that. - */ - int getSerializedSize(); - // ----------------------------------------------------------------- // Comparison and hashing @@ -144,6 +124,7 @@ public interface Message { * @param other object to be compared for equality with this message * @return <tt>true</tt> if the specified object is equal to this message */ + @Override boolean equals(Object other); /** @@ -154,6 +135,7 @@ public interface Message { * @return the hash code value for this message * @see Map#hashCode() */ + @Override int hashCode(); // ----------------------------------------------------------------- @@ -163,67 +145,22 @@ public interface Message { * Converts the message to a string in protocol buffer text format. This is * just a trivial wrapper around {@link TextFormat#printToString(Message)}. */ + @Override String toString(); - /** - * Serializes the message to a {@code ByteString} and returns it. This is - * just a trivial wrapper around - * {@link #writeTo(CodedOutputStream)}. - */ - ByteString toByteString(); - - /** - * Serializes the message to a {@code byte} array and returns it. This is - * just a trivial wrapper around - * {@link #writeTo(CodedOutputStream)}. - */ - byte[] toByteArray(); - - /** - * Serializes the message and writes it to {@code output}. This is just a - * trivial wrapper around {@link #writeTo(CodedOutputStream)}. This does - * not flush or close the stream. - * <p> - * NOTE: Protocol Buffers are not self-delimiting. Therefore, if you write - * any more data to the stream after the message, you must somehow ensure - * that the parser on the receiving end does not interpret this as being - * part of the protocol message. This can be done e.g. by writing the size - * of the message before the data, then making sure to limit the input to - * that size on the receiving end (e.g. by wrapping the InputStream in one - * which limits the input). Alternatively, just use - * {@link #writeDelimitedTo(OutputStream)}. - */ - void writeTo(OutputStream output) throws IOException; - - /** - * Like {@link #writeTo(OutputStream)}, but writes the size of the message - * as a varint before writing the data. This allows more data to be written - * to the stream after the message without the need to delimit the message - * data yourself. Use {@link Builder#mergeDelimitedFrom(InputStream)} (or - * the static method {@code YourMessageType.parseDelimitedFrom(InputStream)}) - * to parse messages written by this method. - */ - void writeDelimitedTo(OutputStream output) throws IOException; - // ================================================================= // Builders - /** - * Constructs a new builder for a message of the same type as this message. - */ + // (From MessageLite, re-declared here only for return type covariance.) Builder newBuilderForType(); - - /** - * Constructs a builder initialized with the current message. Use this to - * derive a new message from the current one. - */ Builder toBuilder(); /** * Abstract interface implemented by Protocol Message builders. */ - public static interface Builder extends Cloneable { - /** Resets all fields to their default values. */ + interface Builder extends MessageLite.Builder { + // (From MessageLite.Builder, re-declared here only for return type + // covariance.) Builder clear(); /** @@ -244,71 +181,14 @@ public interface Message { */ Builder mergeFrom(Message other); - /** - * Construct the final message. Once this is called, the Builder is no - * longer valid, and calling any other method may throw a - * NullPointerException. If you need to continue working with the builder - * after calling {@code build()}, {@code clone()} it first. - * @throws UninitializedMessageException The message is missing one or more - * required fields (i.e. {@link #isInitialized()} returns false). - * Use {@link #buildPartial()} to bypass this check. - */ + // (From MessageLite.Builder, re-declared here only for return type + // covariance.) Message build(); - - /** - * Like {@link #build()}, but does not throw an exception if the message - * is missing required fields. Instead, a partial message is returned. - */ Message buildPartial(); - - /** - * Clones the Builder. - * @see Object#clone() - */ Builder clone(); - - /** - * Returns true if all required fields in the message and all embedded - * messages are set, false otherwise. - */ - boolean isInitialized(); - - /** - * Parses a message of this type from the input and merges it with this - * message, as if using {@link Builder#mergeFrom(Message)}. - * - * <p>Warning: This does not verify that all required fields are present in - * the input message. If you call {@link #build()} without setting all - * required fields, it will throw an {@link UninitializedMessageException}, - * which is a {@code RuntimeException} and thus might not be caught. There - * are a few good ways to deal with this: - * <ul> - * <li>Call {@link #isInitialized()} to verify that all required fields - * are set before building. - * <li>Parse the message separately using one of the static - * {@code parseFrom} methods, then use {@link #mergeFrom(Message)} - * to merge it with this one. {@code parseFrom} will throw an - * {@link InvalidProtocolBufferException} (an {@code IOException}) - * if some required fields are missing. - * <li>Use {@code buildPartial()} to build, which ignores missing - * required fields. - * </ul> - * - * <p>Note: The caller should call - * {@link CodedInputStream#checkLastTagWas(int)} after calling this to - * verify that the last tag seen was the appropriate end-group tag, - * or zero for EOF. - */ Builder mergeFrom(CodedInputStream input) throws IOException; - - /** - * Like {@link Builder#mergeFrom(CodedInputStream)}, but also - * parses extensions. The extensions that you want to be able to parse - * must be registered in {@code extensionRegistry}. Extensions not in - * the registry will be treated as unknown fields. - */ Builder mergeFrom(CodedInputStream input, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) throws IOException; /** @@ -317,10 +197,8 @@ public interface Message { */ Descriptors.Descriptor getDescriptorForType(); - /** - * Get the message's type's default instance. - * See {@link Message#getDefaultInstanceForType()}. - */ + // (From MessageLite.Builder, re-declared here only for return type + // covariance.) Message getDefaultInstanceForType(); /** @@ -399,92 +277,29 @@ public interface Message { // --------------------------------------------------------------- // Convenience methods. - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream)}. - */ + // (From MessageLite.Builder, re-declared here only for return type + // covariance.) Builder mergeFrom(ByteString data) throws InvalidProtocolBufferException; - - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. - */ Builder mergeFrom(ByteString data, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) + throws InvalidProtocolBufferException; + Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException; + Builder mergeFrom(byte[] data, int off, int len) throws InvalidProtocolBufferException; - - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream)}. - */ - public Builder mergeFrom(byte[] data) throws InvalidProtocolBufferException; - - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream)}. - */ - public Builder mergeFrom(byte[] data, int off, int len) throws InvalidProtocolBufferException; - - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. - */ Builder mergeFrom(byte[] data, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException; - - /** - * Parse {@code data} as a message of this type and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. - */ Builder mergeFrom(byte[] data, int off, int len, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException; - - /** - * Parse a message of this type from {@code input} and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream)}. Note that this method always - * reads the <i>entire</i> input (unless it throws an exception). If you - * want it to stop earlier, you will need to wrap your input in some - * wrapper stream that limits reading. Or, use - * {@link Message#writeDelimitedTo(OutputStream)} to write your message and - * {@link #mergeDelimitedFrom(InputStream)} to read it. - * <p> - * Despite usually reading the entire input, this does not close the stream. - */ Builder mergeFrom(InputStream input) throws IOException; - - /** - * Parse a message of this type from {@code input} and merge it with the - * message being built. This is just a small wrapper around - * {@link #mergeFrom(CodedInputStream,ExtensionRegistry)}. - */ Builder mergeFrom(InputStream input, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) throws IOException; - - /** - * Like {@link #mergeFrom(InputStream)}, but does not read until EOF. - * Instead, the size of the message (encoded as a varint) is read first, - * then the message data. Use - * {@link Message#writeDelimitedTo(OutputStream)} to write messages in this - * format. - */ Builder mergeDelimitedFrom(InputStream input) throws IOException; - - /** - * Like {@link #mergeDelimitedFrom(InputStream)} but supporting extensions. - */ Builder mergeDelimitedFrom(InputStream input, - ExtensionRegistry extensionRegistry) + ExtensionRegistryLite extensionRegistry) throws IOException; } } |