// Protocol Buffers - Google's data interchange format // Copyright 2008 Google Inc. // http://code.google.com/p/protobuf/ // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. using System; using System.Collections.Generic; using System.IO; using Google.ProtocolBuffers.Descriptors; namespace Google.ProtocolBuffers { /// /// Non-generic interface for all members whose signatures don't require knowledge of /// the type being built. The generic interface extends this one. Some methods return /// either an IBuilder or an IMessage; in these cases the generic interface redeclares /// the same method with a type-specific signature. Implementations are encouraged to /// use explicit interface implemenation for the non-generic form. This mirrors /// how IEnumerable and IEnumerable<T> work. /// public interface IBuilder { /// /// Returns true iff all required fields in the message and all /// embedded messages are set. /// bool Initialized { get; } /// /// Behaves like the equivalent property in IMessage<T>. /// The returned map may or may not reflect future changes to the builder. /// Either way, the returned map is unmodifiable. /// IDictionary AllFields { get; } /// /// Allows getting and setting of a field. /// /// /// /// object this[FieldDescriptor field] { get; set; } /// /// Get the message's type's descriptor. /// /// MessageDescriptor DescriptorForType { get; } /// /// /// /// /// int GetRepeatedFieldCount(FieldDescriptor field); /// /// Allows getting and setting of a repeated field value. /// /// object this[FieldDescriptor field, int index] { get; set; } /// /// /// bool HasField(FieldDescriptor field); /// /// /// UnknownFieldSet UnknownFields { get; set; } #region Non-generic versions of generic methods in IBuilder IBuilder Clear(); IBuilder MergeFrom(IMessage other); IMessage Build(); IMessage BuildPartial(); IBuilder Clone(); IBuilder MergeFrom(CodedInputStream input); IBuilder MergeFrom(CodedInputStream codedInputStream, ExtensionRegistry extensionRegistry); IMessage DefaultInstanceForType { get; } IBuilder CreateBuilderForField(FieldDescriptor field); IBuilder ClearField(FieldDescriptor field); IBuilder AddRepeatedField(FieldDescriptor field, object value); IBuilder MergeUnknownFields(UnknownFieldSet unknownFields); IBuilder MergeFrom(ByteString data); IBuilder MergeFrom(ByteString data, ExtensionRegistry extensionRegistry); IBuilder MergeFrom(byte[] data); IBuilder MergeFrom(byte[] data, ExtensionRegistry extensionRegistry); IBuilder MergeFrom(Stream input); IBuilder MergeFrom(Stream input, ExtensionRegistry extensionRegistry); #endregion } /// /// Interface implemented by Protocol Message builders. /// TODO(jonskeet): Consider "SetXXX" methods returning the builder, as well as the properties. /// /// Type of message public interface IBuilder : IBuilder where T : IMessage { /// /// Resets all fields to their default values. /// new IBuilder Clear(); /// /// Merge the specified other message into the message being /// built. Merging occurs as follows. For each field: /// For singular primitive fields, if the field is set in , /// then 's value overwrites the value in this message. /// For singular message fields, if the field is set in , /// it is merged into the corresponding sub-message of this message using the same /// merging rules. /// For repeated fields, the elements in are concatenated /// with the elements in this message. /// /// /// IBuilder MergeFrom(T other); /// /// Constructs the final message. Once this is called, this Builder instance /// is no longer valid, and calling any other method may throw a /// NullReferenceException. If you need to continue working with the builder /// after calling Build, call Clone first. /// /// the message /// is missing one or more required fields; use BuildPartial to bypass /// this check new T Build(); /// /// Like Build(), but does not throw an exception if the message is missing /// required fields. Instead, a partial message is returned. /// new T BuildPartial(); /// /// Clones this builder. /// TODO(jonskeet): Explain depth of clone. /// new IBuilder Clone(); /// /// Parses a message of this type from the input and merges it with this /// message, as if using MergeFrom(IMessage<T>). /// /// /// Warning: This does not verify that all required fields are present /// in the input message. If you call Build() without setting all /// required fields, it will throw an UninitializedMessageException. /// There are a few good ways to deal with this: /// /// Call Initialized to verify to verify that all required fields are /// set before building. /// Parse the message separately using one of the static ParseFrom /// methods, then use MergeFrom(IMessage<T>) to merge it with /// this one. ParseFrom will throw an InvalidProtocolBufferException /// (an IOException) if some required fields are missing. /// Use BuildPartial to build, which ignores missing required fields. /// /// new IBuilder MergeFrom(CodedInputStream input); /// /// Like MergeFrom(CodedInputStream), but also parses extensions. /// The extensions that you want to be able to parse must be registered /// in . Extensions not in the registry /// will be treated as unknown fields. /// new IBuilder MergeFrom(CodedInputStream input, ExtensionRegistry extensionRegistry); /// /// Get's the message's type's default instance. /// /// new T DefaultInstanceForType { get; } /// /// Create a builder for messages of the appropriate type for the given field. /// Messages built with this can then be passed to the various mutation properties /// and methods. /// //new IBuilder NewBuilderForField(FieldDescriptor field) where TField : IMessage; /// /// Clears the field. This is exactly equivalent to calling the generated /// Clear method corresponding to the field. /// /// /// new IBuilder ClearField(FieldDescriptor field); /// /// Appends the given value as a new element for the specified repeated field. /// /// the field is not a repeated field, /// the field does not belong to this builder's type, or the value is /// of the incorrect type /// new IBuilder AddRepeatedField(FieldDescriptor field, object value); /// /// Merge some unknown fields into the set for this message. /// new IBuilder MergeUnknownFields(UnknownFieldSet unknownFields); #region Convenience methods // TODO(jonskeet): Implement these as extension methods? /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream). /// new IBuilder MergeFrom(ByteString data); /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream, ExtensionRegistry). /// new IBuilder MergeFrom(ByteString data, ExtensionRegistry extensionRegistry); /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream). /// new IBuilder MergeFrom(byte[] data); /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream, ExtensionRegistry). /// new IBuilder MergeFrom(byte[] data, ExtensionRegistry extensionRegistry); /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream). Note that this method always reads /// the entire input (unless it throws an exception). If you want it to /// stop earlier, you will need to wrap the input in a wrapper /// stream which limits reading. Despite usually reading the entire /// stream, this method never closes the stream. /// new IBuilder MergeFrom(Stream input); /// /// Parse as a message of this type and merge /// it with the message being built. This is just a small wrapper around /// MergeFrom(CodedInputStream, ExtensionRegistry). /// new IBuilder MergeFrom(Stream input, ExtensionRegistry extensionRegistry); #endregion } }