1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Protocol Buffer (Message) Descriptor class.
17
 */
18

19
goog.provide('goog.proto2.Descriptor');
20
goog.provide('goog.proto2.Metadata');
21

22
goog.require('goog.array');
23
goog.require('goog.asserts');
24
goog.require('goog.object');
25
goog.require('goog.string');
26

27

28
/**
29
 * @typedef {{name: (string|undefined),
30
 *            fullName: (string|undefined),
31
 *            containingType: (goog.proto2.Message|undefined)}}
32
 */
33
goog.proto2.Metadata;
34

35

36

37
/**
38
 * A class which describes a Protocol Buffer 2 Message.
39
 *
40
 * @param {function(new:goog.proto2.Message)} messageType Constructor for
41
 *      the message class that this descriptor describes.
42
 * @param {!goog.proto2.Metadata} metadata The metadata about the message that
43
 *      will be used to construct this descriptor.
44
 * @param {Array<!goog.proto2.FieldDescriptor>} fields The fields of the
45
 *      message described by this descriptor.
46
 *
47
 * @constructor
48
 * @final
49
 */
50
goog.proto2.Descriptor = function(messageType, metadata, fields) {
51

52
  /**
53
   * @type {function(new:goog.proto2.Message)}
54
   * @private
55
   */
56
  this.messageType_ = messageType;
57

58
  /**
59
   * @type {?string}
60
   * @private
61
   */
62
  this.name_ = metadata.name || null;
63

64
  /**
65
   * @type {?string}
66
   * @private
67
   */
68
  this.fullName_ = metadata.fullName || null;
69

70
  /**
71
   * @type {goog.proto2.Message|undefined}
72
   * @private
73
   */
74
  this.containingType_ = metadata.containingType;
75

76
  /**
77
   * The fields of the message described by this descriptor.
78
   * @type {!Object<number, !goog.proto2.FieldDescriptor>}
79
   * @private
80
   */
81
  this.fields_ = {};
82

83
  for (var i = 0; i < fields.length; i++) {
84
    var field = fields[i];
85
    this.fields_[field.getTag()] = field;
86
  }
87
};
88

89

90
/**
91
 * Returns the name of the message, if any.
92
 *
93
 * @return {?string} The name.
94
 */
95
goog.proto2.Descriptor.prototype.getName = function() {
96
  return this.name_;
97
};
98

99

100
/**
101
 * Returns the full name of the message, if any.
102
 *
103
 * @return {?string} The name.
104
 */
105
goog.proto2.Descriptor.prototype.getFullName = function() {
106
  return this.fullName_;
107
};
108

109

110
/**
111
 * Returns the descriptor of the containing message type or null if none.
112
 *
113
 * @return {goog.proto2.Descriptor} The descriptor.
114
 */
115
goog.proto2.Descriptor.prototype.getContainingType = function() {
116
  if (!this.containingType_) {
117
    return null;
118
  }
119

120
  return this.containingType_.getDescriptor();
121
};
122

123

124
/**
125
 * Returns the fields in the message described by this descriptor ordered by
126
 * tag.
127
 *
128
 * @return {!Array<!goog.proto2.FieldDescriptor>} The array of field
129
 *     descriptors.
130
 */
131
goog.proto2.Descriptor.prototype.getFields = function() {
132
  /**
133
   * @param {!goog.proto2.FieldDescriptor} fieldA First field.
134
   * @param {!goog.proto2.FieldDescriptor} fieldB Second field.
135
   * @return {number} Negative if fieldA's tag number is smaller, positive
136
   *     if greater, zero if the same.
137
   */
138
  function tagComparator(fieldA, fieldB) {
139
    return fieldA.getTag() - fieldB.getTag();
140
  }
141

142
  var fields = goog.object.getValues(this.fields_);
143
  goog.array.sort(fields, tagComparator);
144

145
  return fields;
146
};
147

148

149
/**
150
 * Returns the fields in the message as a key/value map, where the key is
151
 * the tag number of the field. DO NOT MODIFY THE RETURNED OBJECT. We return
152
 * the actual, internal, fields map for performance reasons, and changing the
153
 * map can result in undefined behavior of this library.
154
 *
155
 * @return {!Object<number, !goog.proto2.FieldDescriptor>} The field map.
156
 */
157
goog.proto2.Descriptor.prototype.getFieldsMap = function() {
158
  return this.fields_;
159
};
160

161

162
/**
163
 * Returns the field matching the given name, if any. Note that
164
 * this method searches over the *original* name of the field,
165
 * not the camelCase version.
166
 *
167
 * @param {string} name The field name for which to search.
168
 *
169
 * @return {goog.proto2.FieldDescriptor} The field found, if any.
170
 */
171
goog.proto2.Descriptor.prototype.findFieldByName = function(name) {
172
  var valueFound = goog.object.findValue(
173
      this.fields_,
174
      function(field, key, obj) { return field.getName() == name; });
175

176
  return /** @type {goog.proto2.FieldDescriptor} */ (valueFound) || null;
177
};
178

179

180
/**
181
 * Returns the field matching the given tag number, if any.
182
 *
183
 * @param {number|string} tag The field tag number for which to search.
184
 *
185
 * @return {goog.proto2.FieldDescriptor} The field found, if any.
186
 */
187
goog.proto2.Descriptor.prototype.findFieldByTag = function(tag) {
188
  goog.asserts.assert(goog.string.isNumeric(tag));
189
  return this.fields_[parseInt(tag, 10)] || null;
190
};
191

192

193
/**
194
 * Creates an instance of the message type that this descriptor
195
 * describes.
196
 *
197
 * @return {!goog.proto2.Message} The instance of the message.
198
 */
199
goog.proto2.Descriptor.prototype.createMessageInstance = function() {
200
  return new this.messageType_;
201
};
202

203