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 | 127 |
1 files changed, 33 insertions, 94 deletions
diff --git a/java/src/main/java/com/google/protobuf/Message.java b/java/src/main/java/com/google/protobuf/Message.java index 8c29e21..5673d3b 100644 --- a/java/src/main/java/com/google/protobuf/Message.java +++ b/java/src/main/java/com/google/protobuf/Message.java @@ -1,6 +1,6 @@ // Protocol Buffers - Google's data interchange format // Copyright 2008 Google Inc. All rights reserved. -// http://code.google.com/p/protobuf/ +// https://developers.google.com/protocol-buffers/ // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are @@ -48,89 +48,33 @@ import java.util.Map; * * @author kenton@google.com Kenton Varda */ -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 - * this method is an abstract method of the {@code Message} interface - * whereas {@code getDescriptor()} is a static method of a specific class. - * They return the same thing. - */ - Descriptors.Descriptor getDescriptorForType(); +public interface Message extends MessageLite, MessageOrBuilder { // (From MessageLite, re-declared here only for return type covariance.) - Message getDefaultInstanceForType(); - - /** - * Returns a collection of all the fields in this message which are set - * and their corresponding values. A singular ("required" or "optional") - * field is set iff hasField() returns true for that field. A "repeated" - * field is set iff getRepeatedFieldSize() is greater than zero. The - * values are exactly what would be returned by calling - * {@link #getField(Descriptors.FieldDescriptor)} for each field. The map - * is guaranteed to be a sorted map, so iterating over it will return fields - * in order by field number. - */ - Map<Descriptors.FieldDescriptor, Object> getAllFields(); - - /** - * Returns true if the given field is set. This is exactly equivalent to - * calling the generated "has" accessor method corresponding to the field. - * @throws IllegalArgumentException The field is a repeated field, or - * {@code field.getContainingType() != getDescriptorForType()}. - */ - boolean hasField(Descriptors.FieldDescriptor field); - - /** - * Obtains the value of the given field, or the default value if it is - * not set. For primitive fields, the boxed primitive value is returned. - * For enum fields, the EnumValueDescriptor for the value is returend. For - * embedded message fields, the sub-message is returned. For repeated - * fields, a java.util.List is returned. - */ - Object getField(Descriptors.FieldDescriptor field); - - /** - * Gets the number of elements of a repeated field. This is exactly - * equivalent to calling the generated "Count" accessor method corresponding - * to the field. - * @throws IllegalArgumentException The field is not a repeated field, or - * {@code field.getContainingType() != getDescriptorForType()}. - */ - int getRepeatedFieldCount(Descriptors.FieldDescriptor field); - - /** - * Gets an element of a repeated field. For primitive fields, the boxed - * primitive value is returned. For enum fields, the EnumValueDescriptor - * for the value is returend. For embedded message fields, the sub-message - * is returned. - * @throws IllegalArgumentException The field is not a repeated field, or - * {@code field.getContainingType() != getDescriptorForType()}. - */ - Object getRepeatedField(Descriptors.FieldDescriptor field, int index); + Parser<? extends Message> getParserForType(); - /** Get the {@link UnknownFieldSet} for this message. */ - UnknownFieldSet getUnknownFields(); // ----------------------------------------------------------------- // Comparison and hashing /** * Compares the specified object with this message for equality. Returns - * <tt>true</tt> if the given object is a message of the same type (as + * {@code true} if the given object is a message of the same type (as * defined by {@code getDescriptorForType()}) and has identical values for - * all of its fields. + * all of its fields. Subclasses must implement this; inheriting + * {@code Object.equals()} is incorrect. * * @param other object to be compared for equality with this message - * @return <tt>true</tt> if the specified object is equal to this message + * @return {@code true} if the specified object is equal to this message */ @Override boolean equals(Object other); /** * Returns the hash code value for this message. The hash code of a message - * is defined to be <tt>getDescriptor().hashCode() ^ map.hashCode()</tt>, - * where <tt>map</tt> is a map of field numbers to field values. + * should mix the message's type (object identity of the descriptor) with its + * contents (known and unknown field values). Subclasses must implement this; + * inheriting {@code Object.hashCode()} is incorrect. * * @return the hash code value for this message * @see Map#hashCode() @@ -143,7 +87,8 @@ public interface Message extends MessageLite { /** * Converts the message to a string in protocol buffer text format. This is - * just a trivial wrapper around {@link TextFormat#printToString(Message)}. + * just a trivial wrapper around {@link + * TextFormat#printToString(MessageOrBuilder)}. */ @Override String toString(); @@ -158,7 +103,7 @@ public interface Message extends MessageLite { /** * Abstract interface implemented by Protocol Message builders. */ - interface Builder extends MessageLite.Builder { + interface Builder extends MessageLite.Builder, MessageOrBuilder { // (From MessageLite.Builder, re-declared here only for return type // covariance.) Builder clear(); @@ -197,17 +142,6 @@ public interface Message extends MessageLite { */ Descriptors.Descriptor getDescriptorForType(); - // (From MessageLite.Builder, re-declared here only for return type - // covariance.) - Message getDefaultInstanceForType(); - - /** - * Like {@link Message#getAllFields()}. The returned map may or may not - * reflect future changes to the builder. Either way, the returned map is - * itself unmodifiable. - */ - Map<Descriptors.FieldDescriptor, Object> getAllFields(); - /** * Create a Builder for messages of the appropriate type for the given * field. Messages built with this can then be passed to setField(), @@ -215,11 +149,23 @@ public interface Message extends MessageLite { */ Builder newBuilderForField(Descriptors.FieldDescriptor field); - /** Like {@link Message#hasField(Descriptors.FieldDescriptor)} */ - boolean hasField(Descriptors.FieldDescriptor field); - - /** Like {@link Message#getField(Descriptors.FieldDescriptor)} */ - Object getField(Descriptors.FieldDescriptor field); + /** + * Get a nested builder instance for the given field. + * <p> + * Normally, we hold a reference to the immutable message object for the + * message type field. Some implementations(the generated message builders), + * however, can also hold a reference to the builder object (a nested + * builder) for the field. + * <p> + * If the field is already backed up by a nested builder, the nested builder + * will be returned. Otherwise, a new field builder will be created and + * returned. The original message field (if exist) will be merged into the + * field builder, which will then be nested into its parent builder. + * <p> + * NOTE: implementations that do not support nested builders will throw + * <code>UnsupportedException</code>. + */ + Builder getFieldBuilder(Descriptors.FieldDescriptor field); /** * Sets a field to the given value. The value must be of the correct type @@ -235,14 +181,10 @@ public interface Message extends MessageLite { Builder clearField(Descriptors.FieldDescriptor field); /** - * Like {@link Message#getRepeatedFieldCount(Descriptors.FieldDescriptor)} + * Clears the oneof. This is exactly equivalent to calling the generated + * "clear" accessor method corresponding to the oneof. */ - int getRepeatedFieldCount(Descriptors.FieldDescriptor field); - - /** - * Like {@link Message#getRepeatedField(Descriptors.FieldDescriptor,int)} - */ - Object getRepeatedField(Descriptors.FieldDescriptor field, int index); + Builder clearOneof(Descriptors.OneofDescriptor oneof); /** * Sets an element of a repeated field to the given value. The value must @@ -262,9 +204,6 @@ public interface Message extends MessageLite { */ Builder addRepeatedField(Descriptors.FieldDescriptor field, Object value); - /** Get the {@link UnknownFieldSet} for this message. */ - UnknownFieldSet getUnknownFields(); - /** Set the {@link UnknownFieldSet} for this message. */ Builder setUnknownFields(UnknownFieldSet unknownFields); |