Class: WSDL::XML::Element Private

Inherits:
Object
  • Object
show all
Defined in:
lib/wsdl/xml/element.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Represents an XML element definition used for building SOAP messages.

Elements are the building blocks of SOAP message structures. They can be either simple types (with a base type like string or integer) or complex types (with child elements). Elements track their cardinality (singular vs. array), namespace qualification, and support detection of recursive type definitions.

Constant Summary collapse

EMPTY_CHILDREN =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Canonical frozen empty array shared for elements without children.

Returns:

[].freeze
EMPTY_ATTRIBUTES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Canonical frozen empty array shared for elements without attributes.

Returns:

[].freeze
KIND_STRINGS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Pre-frozen kind strings used in #to_definition_h to avoid per-call +Symbol#to_s+ allocations.

Returns:

  • (Hash{Symbol => String}) 
{ simple: 'simple', complex: 'complex', recursive: 'recursive' }.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Element

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new Element with default values.



40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/wsdl/xml/element.rb', line 40

def initialize
  @children     = EMPTY_CHILDREN
  @attributes   = EMPTY_ATTRIBUTES
  @definition_h = nil
  @recursive    = false
  @singular     = true
  @min_occurs   = '1'
  @max_occurs   = '1'
  @any_content  = false
  @nillable     = false
  @list         = false
end

Instance Attribute Details

#any_content ⇒ Boolean Also known as: any_content?

Whether this element allows arbitrary content via xs:any wildcard. When true, the element can contain any well-formed XML elements beyond those explicitly defined in the schema.

Returns:

  • (Boolean) —

    true if arbitrary content is allowed



188
189
190
 
# File 'lib/wsdl/xml/element.rb', line 188

def any_content
  @any_content
end

#attributes ⇒ Array<Attribute>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The XML attributes defined on this element.

Returns:

  • (Array<Attribute>) —

    the attribute definitions



194
195
196
 
# File 'lib/wsdl/xml/element.rb', line 194

def attributes
  @attributes
end

#base_type ⇒ String?

The base type name for simple type elements (e.g., 'xsd:string').

Returns:

  • (String, nil) —

    the base type name, or nil for complex types



114
115
116
 
# File 'lib/wsdl/xml/element.rb', line 114

def base_type
  @base_type
end

#children ⇒ Array<Element>

The child elements for complex type elements.

Returns:

  • (Array<Element>) —

    the child elements



181
182
183
 
# File 'lib/wsdl/xml/element.rb', line 181

def children
  @children
end

#complex_type_id ⇒ String?

The complex type ID for tracking recursive type definitions. Format is "namespace:localName".

Returns:

  • (String, nil) —

    the complex type identifier



176
177
178
 
# File 'lib/wsdl/xml/element.rb', line 176

def complex_type_id
  @complex_type_id
end

#form ⇒ String

The element form ('qualified' or 'unqualified'). Qualified elements include namespace prefixes in the XML output.

Returns:

  • (String) —

    the element form



72
73
74
 
# File 'lib/wsdl/xml/element.rb', line 72

def form
  @form
end

#list ⇒ Boolean Also known as: list?

Whether this element is an xs:list type (whitespace-separated values).

Returns:

  • (Boolean) —

    true for list-derived simple types



119
120
121
 
# File 'lib/wsdl/xml/element.rb', line 119

def list
  @list
end

#max_occurs ⇒ String

Maximum occurrences for this element in schema terms.

Returns:

  • (String) —

    maxOccurs value (default: '1')



136
137
138
 
# File 'lib/wsdl/xml/element.rb', line 136

def max_occurs
  @max_occurs
end

#min_occurs ⇒ String

Minimum occurrences for this element in schema terms.

Returns:

  • (String) —

    minOccurs value (default: '1')



131
132
133
 
# File 'lib/wsdl/xml/element.rb', line 131

def min_occurs
  @min_occurs
end

#name ⇒ String

The local name of this element.

Returns:

  • (String) —

    the element name



61
62
63
 
# File 'lib/wsdl/xml/element.rb', line 61

def name
  @name
end

#namespace ⇒ String?

The namespace URI for this element.

Returns:

  • (String, nil) —

    the namespace URI



66
67
68
 
# File 'lib/wsdl/xml/element.rb', line 66

def namespace
  @namespace
end

#nillable ⇒ Boolean Also known as: nillable?

Whether this element can have a nil value (xsi:nil="true"). This corresponds to the nillable="true" attribute in the XSD schema.

Returns:

  • (Boolean) —

    true if the element is nillable



152
153
154
 
# File 'lib/wsdl/xml/element.rb', line 152

def nillable
  @nillable
end

#parent ⇒ Element?

The parent element in the element tree.

Returns:

  • (Element, nil) —

    the parent element



56
57
58
 
# File 'lib/wsdl/xml/element.rb', line 56

def parent
  @parent
end

#recursive_type ⇒ String?

The name of the recursive type definition, if any.

Returns:

  • (String, nil) —

    the recursive type name



169
170
171
 
# File 'lib/wsdl/xml/element.rb', line 169

def recursive_type
  @recursive_type
end

#singular ⇒ Boolean Also known as: singular?

Whether this element appears at most once (singular) or can repeat (array).

Returns:

  • (Boolean) —

    true for singular elements, false for repeating elements



125
126
127
 
# File 'lib/wsdl/xml/element.rb', line 125

def singular
  @singular
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Compares two elements by their properties (excluding parent reference).

Performs deep comparison including children and attributes.

rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- all fields compared

Parameters:

  • other (Object) —

    the object to compare

Returns:

  • (Boolean) —

    true if elements have identical properties



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/wsdl/xml/element.rb', line 260

def ==(other)
  return false unless other.is_a?(self.class)

  name == other.name &&
    namespace == other.namespace &&
    form == other.form &&
    base_type == other.base_type &&
    min_occurs == other.min_occurs &&
    max_occurs == other.max_occurs &&
    singular == other.singular &&
    nillable == other.nillable &&
    list == other.list &&
    any_content == other.any_content &&
    recursive_type == other.recursive_type &&
    complex_type_id == other.complex_type_id &&
    children == other.children &&
    attributes == other.attributes
end

#complex_type? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether this element is a complex type.

Complex types contain child elements rather than simple text content. Recursive elements are also considered complex types.

Returns:

  • (Boolean) —

    true if this is a complex type element



107
108
109
 
# File 'lib/wsdl/xml/element.rb', line 107

def complex_type?
  !simple_type?
end

#freeze ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deep-freezes this element by also freezing the mutable +@children+ array and eagerly computing the #to_definition_h result.

The +@attributes+ array is already frozen by the custom setter, so only +@children+ needs explicit freezing here.

Computing +@definition_h+ before +super+ ensures child elements (which are already frozen at this point) return their cached hashes, eliminating redundant hash construction for shared type-cache children.

Returns:

  • (self) 


222
223
224
225
226
227
228
 
# File 'lib/wsdl/xml/element.rb', line 222

def freeze
  return self if frozen?

  @children.freeze
  @definition_h = build_definition_h
  super
end

#hash ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns hash code based on element properties (excluding parent).

Returns:

  • (Integer) —

    hash code based on element properties (excluding parent)



283
284
285
286
287
288
289
 
# File 'lib/wsdl/xml/element.rb', line 283

def hash
  [
    name, namespace, form, base_type, min_occurs, max_occurs,
    singular, nillable, list, any_content, recursive_type, complex_type_id,
    children, attributes
  ].hash
end

#kind ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the kind of this element.

Provides a three-way classification for introspection. Note: recursive elements are a subset of complex types. Use #simple_type? and #complex_type? for binary dispatch.

Returns:

  • (Symbol) —

    :recursive, :simple, or :complex



81
82
83
84
85
86
87
88
89
 
# File 'lib/wsdl/xml/element.rb', line 81

def kind
  if recursive?
    :recursive
  elsif base_type
    :simple
  else
    :complex
  end
end

#optional? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the element is optional (minOccurs=0).

Returns:

  • (Boolean) —

    true if the element is optional (minOccurs=0)



139
140
141
 
# File 'lib/wsdl/xml/element.rb', line 139

def optional?
  min_occurs.to_s == '0'
end

#recursive? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether this element's type is defined recursively.

A recursive type definition means one of this element's ancestors has the same complex type as this element, which would cause infinite recursion if fully expanded.

Returns:

  • (Boolean) —

    true if this element has a recursive type definition



162
163
164
 
# File 'lib/wsdl/xml/element.rb', line 162

def recursive?
  !!recursive_type
end

#required? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the element is required (minOccurs>0).

Returns:

  • (Boolean) —

    true if the element is required (minOccurs>0)



144
145
146
 
# File 'lib/wsdl/xml/element.rb', line 144

def required?
  !optional?
end

#simple_type? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns whether this element is a simple type.

Simple types have a base type and contain only text content, not child elements.

Returns:

  • (Boolean) —

    true if this is a simple type element



97
98
99
 
# File 'lib/wsdl/xml/element.rb', line 97

def simple_type?
  !!base_type
end

#to_a(memo = [], stack = []) ⇒ Array<Array>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts this element and its children to an Array representation for inspection.

Each element is represented as a tuple of [path, data], where path is an array of element names from the root, and data is a hash containing the element's properties.

rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- straightforward tree traversal with kind dispatch

Examples:

element.to_a
# => [
#      [["user"], { namespace: "http://example.com", form: "qualified", singular: true }],
#      [["user", "name"], { namespace: nil, form: "unqualified", singular: true, type: "xsd:string" }]
#    ]

Parameters:

  • memo (Array) (defaults to: []) —

    accumulator for recursive traversal (internal use)

  • stack (Array<String>) (defaults to: []) —

    current path of element names (internal use)

Returns:

  • (Array<Array>) —

    array of [path, data] tuples



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/wsdl/xml/element.rb', line 309

def to_a(memo = [], stack = [])
  new_stack = stack + [name]
  data = {
    namespace:,
    form:,
    singular: singular?,
    min_occurs:,
    max_occurs:
  }

  data[:kind] = kind
  data[:attributes] = attributes.map(&:to_h) unless attributes.empty?

  case kind
  when :recursive
    data[:recursive_type] = recursive_type
  when :simple
    data[:type] = base_type
    data[:list] = list?
  when :complex
    data[:any_content] = any_content?
  end

  memo << [new_stack, data]
  children.each { |child| child.to_a(memo, new_stack) } if kind == :complex

  memo
end

#to_definition_h ⇒ Hash{Symbol => Object}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a definition-oriented hash representation of the element tree.

Converts this element and all children/attributes into plain hashes suitable for storage in a Definition. The format preserves all schema properties needed by consumers (Response::Parser, Response::Builder, Request::Validator) and can be round-tripped through serialization.

Examples:

element.to_definition_h
# => { name: "user", namespace: "http://example.com", form: "qualified",
#      type: "complex", xsd_type: nil, min_occurs: 1, max_occurs: 1,
#      nillable: false, singular: true, list: false, any_content: false,
#      recursive_type: nil, complex_type_id: nil,
#      children: [...], attributes: [...] }

Returns:

  • (Hash{Symbol => Object}) —

    definition-compatible element hash



248
249
250
 
# File 'lib/wsdl/xml/element.rb', line 248

def to_definition_h
  @definition_h || build_definition_h
end