Class: WSDL::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/wsdl/definition.rb,
lib/wsdl/definition/builder.rb,
lib/wsdl/definition/element_hash.rb

Overview

Abstract representation of a parsed WSDL service.

A Definition is a frozen, serializable snapshot of everything the library knows about a WSDL service — its services, ports, operations, and message structures stored as plain hashes. It serves as the intermediate representation (IR) that downstream consumers (Client, Operation, Response) operate on.

Create a Definition via parse or restore one from a cached hash via load.

Examples:

Parse and cache

definition = WSDL.parse('http://example.com?wsdl')
File.write('cache.json', definition.to_json)

Restore from cache

definition = WSDL.load(JSON.parse(File.read('cache.json')))

See Also:

Defined Under Namespace

Classes: AttributeHash, Builder, ElementHash

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data) ⇒ Definition

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 Definition from internal data.

This constructor is intended for internal use by Builder and from_h. Users should create Definitions via WSDL.parse or WSDL.load.

Parameters:

  • data (Hash{Symbol => Object}) —

    the internal definition data



37
38
39
40
 
# File 'lib/wsdl/definition.rb', line 37

def initialize(data)
  @data = deep_freeze(data)
  freeze
end

Class Method Details

.from_h(hash) ⇒ Definition

Restores a Definition from a serialized Hash.

Validates the schema version and raises if it doesn't match the current library version.

Parameters:

  • hash (Hash{String => Object}) —

    serialized hash from #to_h

Returns:

Raises:

  • (ArgumentError) —

    if the schema version doesn't match



317
318
319
320
321
322
323
324
325
326
327
 
# File 'lib/wsdl/definition.rb', line 317

def self.from_h(hash)
  version = hash['schema_version'] || hash[:schema_version]

  unless version == Builder::SCHEMA_VERSION
    raise ArgumentError,
      "Definition schema version mismatch: expected #{Builder::SCHEMA_VERSION}, " \
      "got #{version.inspect}. Please re-parse the WSDL with WSDL.parse."
  end

  new(deserialize(hash))
end

Instance Method Details

#build_issues ⇒ Array<Hash{Symbol => String}>

Returns build issues encountered during Definition construction.

Each entry records an operation that could not be fully resolved and the reason. These operations are included in the Definition with empty message parts.

Examples:

definition.build_issues
# => [{ operation: "GetStatus", error: "Unable to find element ..." }]

Returns:

  • (Array<Hash{Symbol => String}>) —

    build issue entries with :operation and :error keys



95
96
97
 
# File 'lib/wsdl/definition.rb', line 95

def build_issues
  @data[:build_issues] || []
end

#endpoint(service_name, port_name) ⇒ String

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 endpoint URL for a specific service and port.

Parameters:

  • service_name (String) —

    the service name

  • port_name (String) —

    the port name

Returns:

  • (String) —

    the endpoint URL



251
252
253
 
# File 'lib/wsdl/definition.rb', line 251

def endpoint(service_name, port_name)
  @data[:services][service_name][:ports][port_name][:endpoint]
end

#fingerprint ⇒ String

Returns the content-based fingerprint for this Definition.

The fingerprint is derived from all source digests and statuses. It changes when any source document changes or when a previously failing import starts resolving (or vice versa).

Returns:

  • (String) —

    SHA-256 fingerprint (e.g. "sha256:a1b2c3...")



63
64
65
 
# File 'lib/wsdl/definition.rb', line 63

def fingerprint
  @data[:fingerprint]
end

#input(operation_name) ⇒ Array<Hash> #input(service_name, port_name, operation_name) ⇒ Array<Hash>

Returns a developer-friendly view of an operation's input body.

Auto-resolves service and port for single-service/port WSDLs. For multiple services/ports, pass them explicitly.

Returns:

  • (Array<Hash>) —

    element structure with human-readable types



175
176
177
178
 
# File 'lib/wsdl/definition.rb', line 175

def input(*)
  op = resolve_operation(*)
  op[:input][:body].map { |el| project_element(el) }
end

#input_header(operation_name) ⇒ Array<Hash> #input_header(service_name, port_name, operation_name) ⇒ Array<Hash>

Returns a developer-friendly view of an operation's input headers.

Returns:

  • (Array<Hash>) —

    header element structure



185
186
187
188
 
# File 'lib/wsdl/definition.rb', line 185

def input_header(*)
  op = resolve_operation(*)
  op[:input][:header].map { |el| project_element(el) }
end

#operation_data(operation_name) ⇒ Hash #operation_data(service_name, port_name, operation_name) ⇒ Hash

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 full internal operation data for use by Client/Operation.

Parameters:

  • input_name (String, nil) (defaults to: nil) —

    disambiguator for overloaded operations

Returns:

  • (Hash) —

    internal operation hash with full element data



221
222
223
 
# File 'lib/wsdl/definition.rb', line 221

def operation_data(*, input_name: nil)
  resolve_operation(*, input_name:)
end

#operations(service_name = nil, port_name = nil) ⇒ Array<Hash>

Returns all operations. Pass service and port names to filter.

Examples:

definition.operations("UserService", "UserPort")
# => [{ service: "UserService", port: "UserPort", name: "GetUser",
#       style: "document/literal", soap_action: "..." }]

Parameters:

  • service_name (String, nil) (defaults to: nil) —

    optional service name filter

  • port_name (String, nil) (defaults to: nil) —

    optional port name filter

Returns:

  • (Array<Hash>) —

    operation entries with consistent keys



154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/wsdl/definition.rb', line 154

def operations(service_name = nil, port_name = nil)
  result = []
  each_operation(service_name, port_name) do |svc, port, op|
    entry = {
      service: svc, port:, name: op[:name],
      style: op[:input_style], soap_action: op[:soap_action]
    }
    entry[:input_name] = op[:input_name] if op[:input_name]
    result << entry
  end
  result
end

#output(operation_name) ⇒ Array<Hash> #output(service_name, port_name, operation_name) ⇒ Array<Hash>

Returns a developer-friendly view of an operation's output body.

Returns:

  • (Array<Hash>) —

    element structure with human-readable types



195
196
197
198
199
200
 
# File 'lib/wsdl/definition.rb', line 195

def output(*)
  op = resolve_operation(*)
  return [] unless op[:output]

  op[:output][:body].map { |el| project_element(el) }
end

#output_header(operation_name) ⇒ Array<Hash> #output_header(service_name, port_name, operation_name) ⇒ Array<Hash>

Returns a developer-friendly view of an operation's output headers.

Returns:

  • (Array<Hash>) —

    header element structure



207
208
209
210
211
212
 
# File 'lib/wsdl/definition.rb', line 207

def output_header(*)
  op = resolve_operation(*)
  return [] unless op[:output]

  op[:output][:header].map { |el| project_element(el) }
end

#port_type(service_name, port_name) ⇒ String

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 SOAP type namespace URI for a port.

Parameters:

  • service_name (String) —

    the service name

  • port_name (String) —

    the port name

Returns:

  • (String) —

    the SOAP namespace URI



261
262
263
 
# File 'lib/wsdl/definition.rb', line 261

def port_type(service_name, port_name)
  @data[:services][service_name][:ports][port_name][:type]
end

#ports(service_name = nil) ⇒ Array<Hash>

Returns all ports. Pass a service name to filter.

Examples:

definition.ports("UserService")
# => [{ service: "UserService", name: "UserPort", endpoint: "http://..." }]

Parameters:

  • service_name (String, nil) (defaults to: nil) —

    optional service name filter

Returns:

  • (Array<Hash>) —

    port entries with :service, :name, :endpoint keys



138
139
140
141
142
 
# File 'lib/wsdl/definition.rb', line 138

def ports(service_name = nil)
  each_port(service_name).map do |svc_name, port_name, port_data|
    { service: svc_name, name: port_name, endpoint: port_data[:endpoint] }
  end
end

#resolve_service_and_port ⇒ Array(String, String)

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.

Resolves the single service and port for auto-resolution.

rubocop:disable Metrics/AbcSize -- validation requires multiple checks

Returns:

  • (Array(String, String)) —

    service and port names

Raises:

  • (ArgumentError) —

    if ambiguous



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/wsdl/definition.rb', line 271

def resolve_service_and_port
  svcs = @data[:services]
  if svcs.size != 1
    names = svcs.keys.map(&:inspect).join(', ')
    raise ArgumentError, "Cannot auto-resolve service: expected 1, found #{svcs.size} (#{names}). " \
                         'Pass explicit service and port names.'
  end

  svc_name = svcs.keys.first
  ports = svcs[svc_name][:ports]
  if ports.size != 1
    names = ports.keys.map(&:inspect).join(', ')
    raise ArgumentError, "Cannot auto-resolve port for service #{svc_name.inspect}: " \
                         "expected 1, found #{ports.size} (#{names}). " \
                         'Pass explicit service and port names.'
  end

  [svc_name, ports.keys.first]
end

#schema_version ⇒ Integer

Returns the schema version of this Definition's internal format.

Returns:

  • (Integer) 


45
46
47
 
# File 'lib/wsdl/definition.rb', line 45

def schema_version
  @data[:schema_version]
end

#service_name ⇒ String?

Returns the name of the primary service.

Returns:

  • (String, nil) —

    the service name



52
53
54
 
# File 'lib/wsdl/definition.rb', line 52

def service_name
  @data[:service_name]
end

#services ⇒ Array<Hash>

Returns all services. Arguments filter the results.

Examples:

definition.services
# => [{ name: "UserService", ports: ["UserPort", "AdminPort"] }]

Returns:

  • (Array<Hash>) —

    service entries with :name and :ports keys



124
125
126
127
128
 
# File 'lib/wsdl/definition.rb', line 124

def services
  @data[:services].map do |name, data|
    { name:, ports: data[:ports].keys }
  end
end

#sources ⇒ Array<Hash{Symbol => Object}>

Returns source provenance for all documents fetched during parsing.

Each entry records the location, resolution status, content digest, and any error. Provides transparency into what was resolved and enables change detection.

Examples:

definition.sources
# => [{ location: "http://...", status: :resolved, digest: "sha256:...", error: nil },
#     { location: "http://...", status: :failed, digest: nil, error: "404 Not Found" }]

Returns:

  • (Array<Hash{Symbol => Object}>) —

    provenance entries



79
80
81
 
# File 'lib/wsdl/definition.rb', line 79

def sources
  @data[:sources]
end

#to_dsl(operation_name) ⇒ String #to_dsl(service_name, port_name, operation_name) ⇒ String

Returns a pasteable DSL snippet for building a request.

Generates code for both header and body sections that can be copy-pasted into an invoke or prepare block.

Examples:

definition.to_dsl("GetUser")
# => "body do\n  tag('GetUser') do\n    tag('id', 'integer')\n  end\nend"

Returns:

  • (String) —

    Ruby DSL code snippet



237
238
239
240
241
242
243
 
# File 'lib/wsdl/definition.rb', line 237

def to_dsl(*)
  op = resolve_operation(*)
  lines = []
  append_dsl_section(lines, 'header', op[:input][:header])
  append_dsl_section(lines, 'body', op[:input][:body])
  lines.join("\n")
end

#to_h ⇒ Hash{String => Object}

Serializes this Definition to a plain Hash.

The hash is suitable for JSON serialization and can be restored via WSDL.load or from_h. Equivalent to calling WSDL.dump.

Returns:

  • (Hash{String => Object}) —

    serializable hash with string keys



298
299
300
 
# File 'lib/wsdl/definition.rb', line 298

def to_h
  serialize(@data)
end

#to_json ⇒ String

Serializes this Definition to a JSON string.

Returns:

  • (String) —

    JSON representation



305
306
307
 
# File 'lib/wsdl/definition.rb', line 305

def to_json(*)
  JSON.generate(to_h, *)
end

#verify! ⇒ self

Raises if any build issues were recorded during construction.

Call this after WSDL.parse if you want strict behavior — failing on any operation that could not be fully resolved.

Examples:

Strict parsing

definition = WSDL.parse(url)
definition.verify!  # raises if any operations couldn't be fully built

Returns:

  • (self) —

    if no issues

Raises:



111
112
113
114
115
 
# File 'lib/wsdl/definition.rb', line 111

def verify!
  raise DefinitionError, build_issues if build_issues.any?

  self
end