MessageDescriptor.cs 14.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
#region Copyright notice and license
// Protocol Buffers - Google's data interchange format
// Copyright 2008 Google Inc.  All rights reserved.
// 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
// met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion

using System;
using System.Collections.Generic;
35
using System.Collections.ObjectModel;
Jon Skeet's avatar
Jon Skeet committed
36
using System.Linq;
37 38 39 40
#if DOTNET35
// Needed for ReadOnlyDictionary, which does not exist in .NET 3.5
using Google.Protobuf.Collections;
#endif
41 42 43 44 45 46 47 48

namespace Google.Protobuf.Reflection
{
    /// <summary>
    /// Describes a message type.
    /// </summary>
    public sealed class MessageDescriptor : DescriptorBase
    {
49 50 51 52 53 54 55 56 57 58 59 60 61 62
        private static readonly HashSet<string> WellKnownTypeNames = new HashSet<string>
        {
            "google/protobuf/any.proto",
            "google/protobuf/api.proto",
            "google/protobuf/duration.proto",
            "google/protobuf/empty.proto",
            "google/protobuf/wrappers.proto",
            "google/protobuf/timestamp.proto",
            "google/protobuf/field_mask.proto",
            "google/protobuf/source_context.proto",
            "google/protobuf/struct.proto",
            "google/protobuf/type.proto",
        };

63 64
        private readonly IList<FieldDescriptor> fieldsInDeclarationOrder;
        private readonly IList<FieldDescriptor> fieldsInNumberOrder;
65
        private readonly IDictionary<string, FieldDescriptor> jsonFieldMap;
66
        
67
        internal MessageDescriptor(DescriptorProto proto, FileDescriptor file, MessageDescriptor parent, int typeIndex, GeneratedClrTypeInfo generatedCodeInfo)
68 69
            : base(file, file.ComputeFullName(parent, proto.Name), typeIndex)
        {
70 71 72 73
            Proto = proto;
            Parser = generatedCodeInfo?.Parser;
            ClrType = generatedCodeInfo?.ClrType;
            ContainingType = parent;
74

75 76 77 78
            // Note use of generatedCodeInfo. rather than generatedCodeInfo?. here... we don't expect
            // to see any nested oneofs, types or enums in "not actually generated" code... we do
            // expect fields though (for map entry messages).
            Oneofs = DescriptorUtil.ConvertAndMakeReadOnly(
79 80
                proto.OneofDecl,
                (oneof, index) =>
81
                new OneofDescriptor(oneof, file, this, index, generatedCodeInfo.OneofNames[index]));
82

83
            NestedTypes = DescriptorUtil.ConvertAndMakeReadOnly(
84 85
                proto.NestedType,
                (type, index) =>
86
                new MessageDescriptor(type, file, this, index, generatedCodeInfo.NestedTypes[index]));
87

88
            EnumTypes = DescriptorUtil.ConvertAndMakeReadOnly(
89 90
                proto.EnumType,
                (type, index) =>
91
                new EnumDescriptor(type, file, this, index, generatedCodeInfo.NestedEnums[index]));
92

93
            fieldsInDeclarationOrder = DescriptorUtil.ConvertAndMakeReadOnly(
94 95
                proto.Field,
                (field, index) =>
96
                new FieldDescriptor(field, file, this, index, generatedCodeInfo?.PropertyNames[index]));
97
            fieldsInNumberOrder = new ReadOnlyCollection<FieldDescriptor>(fieldsInDeclarationOrder.OrderBy(field => field.FieldNumber).ToArray());
98
            // TODO: Use field => field.Proto.JsonName when we're confident it's appropriate. (And then use it in the formatter, too.)
99
            jsonFieldMap = CreateJsonFieldMap(fieldsInNumberOrder);
100
            file.DescriptorPool.AddSymbol(this);
101
            Fields = new FieldCollection(this);
Jon Skeet's avatar
Jon Skeet committed
102
        }
103

104 105 106 107 108 109
        private static ReadOnlyDictionary<string, FieldDescriptor> CreateJsonFieldMap(IList<FieldDescriptor> fields)
        {
            var map = new Dictionary<string, FieldDescriptor>();
            foreach (var field in fields)
            {
                map[field.Name] = field;
alien's avatar
alien committed
110
                map[field.JsonName] = field;
111 112 113 114
            }
            return new ReadOnlyDictionary<string, FieldDescriptor>(map);
        }

115 116 117
        /// <summary>
        /// The brief name of the descriptor's target.
        /// </summary>
118
        public override string Name => Proto.Name;
119

120
        internal DescriptorProto Proto { get; }
121

Jon Skeet's avatar
Jon Skeet committed
122
        /// <summary>
123
        /// The CLR type used to represent message instances from this descriptor.
Jon Skeet's avatar
Jon Skeet committed
124
        /// </summary>
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
        /// <remarks>
        /// <para>
        /// The value returned by this property will be non-null for all regular fields. However,
        /// if a message containing a map field is introspected, the list of nested messages will include
        /// an auto-generated nested key/value pair message for the field. This is not represented in any
        /// generated type, so this property will return null in such cases.
        /// </para>
        /// <para>
        /// For wrapper types (<see cref="Google.Protobuf.WellKnownTypes.StringValue"/> and the like), the type returned here
        /// will be the generated message type, not the native type used by reflection for fields of those types. Code
        /// using reflection should call <see cref="IsWrapperType"/> to determine whether a message descriptor represents
        /// a wrapper type, and handle the result appropriately.
        /// </para>
        /// </remarks>
        public Type ClrType { get; }
Jon Skeet's avatar
Jon Skeet committed
140

141 142 143 144
        /// <summary>
        /// A parser for this message type.
        /// </summary>
        /// <remarks>
145
        /// <para>
146
        /// As <see cref="MessageDescriptor"/> is not generic, this cannot be statically
147 148 149 150 151 152 153 154 155 156 157 158 159 160
        /// typed to the relevant type, but it should produce objects of a type compatible with <see cref="ClrType"/>.
        /// </para>
        /// <para>
        /// The value returned by this property will be non-null for all regular fields. However,
        /// if a message containing a map field is introspected, the list of nested messages will include
        /// an auto-generated nested key/value pair message for the field. No message parser object is created for
        /// such messages, so this property will return null in such cases.
        /// </para>
        /// <para>
        /// For wrapper types (<see cref="Google.Protobuf.WellKnownTypes.StringValue"/> and the like), the parser returned here
        /// will be the generated message type, not the native type used by reflection for fields of those types. Code
        /// using reflection should call <see cref="IsWrapperType"/> to determine whether a message descriptor represents
        /// a wrapper type, and handle the result appropriately.
        /// </para>
161
        /// </remarks>
162
        public MessageParser Parser { get; }
163

164 165 166
        /// <summary>
        /// Returns whether this message is one of the "well known types" which may have runtime/protoc support.
        /// </summary>
167 168 169 170 171 172 173
        internal bool IsWellKnownType => File.Package == "google.protobuf" && WellKnownTypeNames.Contains(File.Name);

        /// <summary>
        /// Returns whether this message is one of the "wrapper types" used for fields which represent primitive values
        /// with the addition of presence.
        /// </summary>
        internal bool IsWrapperType => File.Package == "google.protobuf" && File.Name == "google/protobuf/wrappers.proto";
174

175 176 177
        /// <value>
        /// If this is a nested type, get the outer descriptor, otherwise null.
        /// </value>
178
        public MessageDescriptor ContainingType { get; }
179 180

        /// <value>
181
        /// A collection of fields, which can be retrieved by name or field number.
182
        /// </value>
183
        public FieldCollection Fields { get; }
184 185 186 187

        /// <value>
        /// An unmodifiable list of this message type's nested types.
        /// </value>
188
        public IList<MessageDescriptor> NestedTypes { get; }
189 190 191 192

        /// <value>
        /// An unmodifiable list of this message type's enum types.
        /// </value>
193
        public IList<EnumDescriptor> EnumTypes { get; }
194

195 196 197
        /// <value>
        /// An unmodifiable list of the "oneof" field collections in this message type.
        /// </value>
198
        public IList<OneofDescriptor> Oneofs { get; }
199 200 201 202 203 204

        /// <summary>
        /// Finds a field by field name.
        /// </summary>
        /// <param name="name">The unqualified name of the field (e.g. "foo").</param>
        /// <returns>The field's descriptor, or null if not found.</returns>
205
        public FieldDescriptor FindFieldByName(String name) => File.DescriptorPool.FindSymbol<FieldDescriptor>(FullName + "." + name);
206 207 208 209 210 211

        /// <summary>
        /// Finds a field by field number.
        /// </summary>
        /// <param name="number">The field number within this message type.</param>
        /// <returns>The field's descriptor, or null if not found.</returns>
212
        public FieldDescriptor FindFieldByNumber(int number) => File.DescriptorPool.FindFieldByNumber(this, number);
213 214 215 216 217 218 219

        /// <summary>
        /// Finds a nested descriptor by name. The is valid for fields, nested
        /// message types, oneofs and enums.
        /// </summary>
        /// <param name="name">The unqualified name of the descriptor, e.g. "Foo"</param>
        /// <returns>The descriptor, or null if not found.</returns>
220 221
        public T FindDescriptor<T>(string name)  where T : class, IDescriptor =>
            File.DescriptorPool.FindSymbol<T>(FullName + "." + name);
222

223 224 225 226 227
        /// <summary>
        /// The (possibly empty) set of custom options for this message.
        /// </summary>
        public CustomOptions CustomOptions => Proto.Options?.CustomOptions ?? CustomOptions.Empty;

228 229 230 231 232
        /// <summary>
        /// Looks up and cross-links all fields and nested types.
        /// </summary>
        internal void CrossLink()
        {
233
            foreach (MessageDescriptor message in NestedTypes)
234 235 236 237
            {
                message.CrossLink();
            }

238
            foreach (FieldDescriptor field in fieldsInDeclarationOrder)
239 240 241 242
            {
                field.CrossLink();
            }

243
            foreach (OneofDescriptor oneof in Oneofs)
244 245 246
            {
                oneof.CrossLink();
            }
247 248 249 250 251
        }

        /// <summary>
        /// A collection to simplify retrieving the field accessor for a particular field.
        /// </summary>
252
        public sealed class FieldCollection
253 254 255
        {
            private readonly MessageDescriptor messageDescriptor;

256
            internal FieldCollection(MessageDescriptor messageDescriptor)
257 258 259
            {
                this.messageDescriptor = messageDescriptor;
            }
Jon Skeet's avatar
Jon Skeet committed
260

261 262 263 264
            /// <value>
            /// Returns the fields in the message as an immutable list, in the order in which they
            /// are declared in the source .proto file.
            /// </value>
265
            public IList<FieldDescriptor> InDeclarationOrder() => messageDescriptor.fieldsInDeclarationOrder;
266 267 268 269 270 271 272

            /// <value>
            /// Returns the fields in the message as an immutable list, in ascending field number
            /// order. Field numbers need not be contiguous, so there is no direct mapping from the
            /// index in the list to the field number; to retrieve a field by field number, it is better
            /// to use the <see cref="FieldCollection"/> indexer.
            /// </value>
273
            public IList<FieldDescriptor> InFieldNumberOrder() => messageDescriptor.fieldsInNumberOrder;
274

275 276 277
            // TODO: consider making this public in the future. (Being conservative for now...)

            /// <value>
278
            /// Returns a read-only dictionary mapping the field names in this message as they're available
279
            /// in the JSON representation to the field descriptors. For example, a field <c>foo_bar</c>
280 281
            /// in the message would result two entries, one with a key <c>fooBar</c> and one with a key
            /// <c>foo_bar</c>, both referring to the same field.
282
            /// </value>
283
            internal IDictionary<string, FieldDescriptor> ByJsonName() => messageDescriptor.jsonFieldMap;
284

285
            /// <summary>
286
            /// Retrieves the descriptor for the field with the given number.
287
            /// </summary>
288 289
            /// <param name="number">Number of the field to retrieve the descriptor for</param>
            /// <returns>The accessor for the given field</returns>
290 291
            /// <exception cref="KeyNotFoundException">The message descriptor does not contain a field
            /// with the given number</exception>
292
            public FieldDescriptor this[int number]
293 294 295 296 297 298 299 300
            {
                get
                {
                    var fieldDescriptor = messageDescriptor.FindFieldByNumber(number);
                    if (fieldDescriptor == null)
                    {
                        throw new KeyNotFoundException("No such field number");
                    }
301
                    return fieldDescriptor;
302 303 304 305
                }
            }

            /// <summary>
306
            /// Retrieves the descriptor for the field with the given name.
307
            /// </summary>
308
            /// <param name="name">Name of the field to retrieve the descriptor for</param>
309
            /// <returns>The descriptor for the given field</returns>
310 311
            /// <exception cref="KeyNotFoundException">The message descriptor does not contain a field
            /// with the given name</exception>
312
            public FieldDescriptor this[string name]
313 314 315 316 317 318 319 320
            {
                get
                {
                    var fieldDescriptor = messageDescriptor.FindFieldByName(name);
                    if (fieldDescriptor == null)
                    {
                        throw new KeyNotFoundException("No such field name");
                    }
321
                    return fieldDescriptor;
322 323
                }
            }
324
        }
325
    }
Jon Skeet's avatar
Jon Skeet committed
326
}