Class: Resync::BaseResourceList

Inherits:
Augmented show all
Includes:
XML::Mapping
Defined in:
lib/resync/shared/base_resource_list.rb

Overview

Base class for root elements containing a list of resources (i.e., <urlset> and <sitemapindex> elements). Subclasses must define a CAPABILITY constant identifying the capability they represent (e.g. resourcelist, changelist).

Instance Attribute Summary collapse

Attributes inherited from Augmented

#links, #metadata

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Augmented

#link_for, #links_for

Constructor Details

#initialize(resources: [], links: [], metadata: nil) ⇒ BaseResourceList

Creates a new BaseResourceList.

Parameters:

  • resources (Array<Resource>) (defaults to: []) —

    The <url> or <sitemap> elements contained in this list.

  • links (Array<Link>) (defaults to: []) —

    Related links (+<rs:ln>+).

  • metadata (Metadata) (defaults to: nil) —

    Metadata about this list. The capability of the metadata must match this implementation class’ CAPABILITY constant.

Raises:

  • (ArgumentError) —

    if the specified metadata does not have the correct capability attribute for this list type.



32
33
34
35
36
 
# File 'lib/resync/shared/base_resource_list.rb', line 32

def initialize(resources: [], links: [], metadata: nil)
  super(links: links)
  self.resources = resources
  self.metadata = metadata
end

Instance Attribute Details

#resources ⇒ Array<Resource>

Returns the <url> or <sitemap> elements contained in this list.

Returns:

  • (Array<Resource>) —

    the <url> or <sitemap> elements contained in this list.



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/resync/shared/base_resource_list.rb', line 13

class BaseResourceList < Augmented
  include ::XML::Mapping

  # ------------------------------------------------------------
  # Attributes

  root_element_name 'urlset'
  array_node :resources, 'url', class: Resource, default_value: []

  # ------------------------------------------------------------
  # Initializer

  # Creates a new +BaseResourceList+.
  #
  # @param resources [Array<Resource>] The +<url>+ or +<sitemap>+ elements contained in this list.
  # @param links [Array<Link>] Related links (+<rs:ln>+).
  # @param metadata [Metadata] Metadata about this list. The +capability+ of the metadata must match this
  #   implementation class' +CAPABILITY+ constant.
  # @raise [ArgumentError] if the specified metadata does not have the correct +capability+ attribute for this list type.
  def initialize(resources: [], links: [], metadata: nil)
    super(links: links)
    self.resources = resources
    self.metadata = metadata
  end

  # ------------------------------------------------------------
  # Custom setters

  # Sets the +resources+ list. +nil+ is treated as an empty list.
  def resources=(value)
    @resources = value || []
  end

  # Sets the metadata.
  #
  # @raise [ArgumentError] if the specified metadata does not have the correct +capability+ attribute for
  #   this list type.
  def metadata=(value)
    @metadata = metadata_with_correct_capability(value)
  end

  # ------------------------------------------------------------
  # Custom getters

  # @return [String] the capability provided by this document
  def capability
    @metadata.capability
  end

  # Finds resources with the specified capability.
  # @param capability [String] the capability.
  # @return [Array<Resource>] those resources having that capability, or an empty array if none exist.
  def resources_for(capability:)
    resources.select { |l| l.capability == capability }
  end

  # Shortcut to find the first resource with the specified capability (in ResourceSync there often
  # should be only one resource with a particular capability)
  # @param capability [String] the capability.
  # @return [Resource] the first resource having that capability, or nil if none exists.
  def resource_for(capability:)
    resources.find { |l| l.capability == capability }
  end

  # ------------------------------------------------------------
  # Overrides

  # Overrides +::XML::Mapping.pre_save+ to declare the Sitemap and ResourceSync namespaces.
  # Used for writing.
  def pre_save(options = { mapping: :_default })
    xml = super(options)
    xml.add_namespace('http://www.sitemaps.org/schemas/sitemap/0.9')
    xml.add_namespace('rs', 'http://www.openarchives.org/rs/terms/')
    xml
  end

  # Initializes the +:_default+ and +:sitemapindex+ mappings on all subclasses, and sets the corresponding
  # root element names (+<urlset>+ and +<sitemapindex>+)
  def self.inherited(base)
    base.use_mapping :_default
    base.root_element_name 'urlset'
    base.use_mapping :sitemapindex
    base.root_element_name 'sitemapindex'
  end

  # ------------------------------------------------------------
  # Private methods

  private

  # ------------------------------
  # Parameter validators

  # Validates the +capability+ attribute in the specified metadata.
  # @raise [ArgumentError] if the specified metadata does not have the correct +capability+ attribute for this list type.
  def metadata_with_correct_capability(metadata)
    capability = self.class::CAPABILITY
    fail ArgumentError, "Missing constant #{self.class}::CAPABILITY" unless capability
    return Metadata.new(capability: capability) unless metadata
    fail ArgumentError, "#{metadata} does not appear to be metadata" unless metadata.respond_to?('capability')
    fail ArgumentError, "Wrong capability for #{self.class.name} metadata; expected '#{capability}', was '#{metadata.capability}'" unless metadata.capability == capability
    metadata
  end

end

Class Method Details

.inherited(base) ⇒ Object

Initializes the :_default and :sitemapindex mappings on all subclasses, and sets the corresponding root element names (+<urlset>+ and <sitemapindex>)



91
92
93
94
95
96
 
# File 'lib/resync/shared/base_resource_list.rb', line 91

def self.inherited(base)
  base.use_mapping :_default
  base.root_element_name 'urlset'
  base.use_mapping :sitemapindex
  base.root_element_name 'sitemapindex'
end

Instance Method Details

#capability ⇒ String

Returns the capability provided by this document.

Returns:

  • (String) —

    the capability provided by this document



58
59
60
 
# File 'lib/resync/shared/base_resource_list.rb', line 58

def capability
  @metadata.capability
end

#metadata=(value) ⇒ Object

Sets the metadata.

Raises:

  • (ArgumentError) —

    if the specified metadata does not have the correct capability attribute for this list type.



50
51
52
 
# File 'lib/resync/shared/base_resource_list.rb', line 50

def metadata=(value)
  @metadata = metadata_with_correct_capability(value)
end

#pre_save(options = { mapping: :_default }) ⇒ Object

Overrides ::XML::Mapping.pre_save to declare the Sitemap and ResourceSync namespaces. Used for writing.



82
83
84
85
86
87
 
# File 'lib/resync/shared/base_resource_list.rb', line 82

def pre_save(options = { mapping: :_default })
  xml = super(options)
  xml.add_namespace('http://www.sitemaps.org/schemas/sitemap/0.9')
  xml.add_namespace('rs', 'http://www.openarchives.org/rs/terms/')
  xml
end

#resource_for(capability:) ⇒ Resource

Shortcut to find the first resource with the specified capability (in ResourceSync there often should be only one resource with a particular capability)

Parameters:

  • capability (String) —

    the capability.

Returns:

  • (Resource) —

    the first resource having that capability, or nil if none exists.



73
74
75
 
# File 'lib/resync/shared/base_resource_list.rb', line 73

def resource_for(capability:)
  resources.find { |l| l.capability == capability }
end

#resources_for(capability:) ⇒ Array<Resource>

Finds resources with the specified capability.

Parameters:

  • capability (String) —

    the capability.

Returns:

  • (Array<Resource>) —

    those resources having that capability, or an empty array if none exist.



65
66
67
 
# File 'lib/resync/shared/base_resource_list.rb', line 65

def resources_for(capability:)
  resources.select { |l| l.capability == capability }
end