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

#at_time, #change, #completed_time, #from_time, #link_for, #links_for, #until_time

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
118
119
120
121
122
123
124
125
126
127
128
 
# 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 { |r| r.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 { |r| r.capability == capability }
  end

  # Finds only those resources falling within the specified time range. Any of the time
  # attributes (+:modified_time+, +:at_time+, +:completed_time+, +:from_time+, +:until_time+)
  # can be used for filtering.
  # @param time_range [Range[Time]] the range of acceptable times (inclusive or exclusive)
  # @param time_attr [Symbol] the time type to filter on: +:modified_time+, +:at_time+,
  #   +:completed_time+, +:from_time+ or +:until_time+
  # @return [Array<Resource>] a lazy enumeration of the resources within the specified range.
  def resources_in(time_range:, time_attr:)
    resources.select { |r| time_range.cover?(r.send(time_attr)) }
  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 argument <#{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>)



102
103
104
105
106
107
 
# File 'lib/resync/shared/base_resource_list.rb', line 102

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.



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

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 { |r| r.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 { |r| r.capability == capability }
end

#resources_in(time_range:, time_attr:) ⇒ Array<Resource>

Finds only those resources falling within the specified time range. Any of the time attributes (:modified_time, :at_time, :completed_time, :from_time, :until_time) can be used for filtering.

Parameters:

  • time_range (Range[Time]) —

    the range of acceptable times (inclusive or exclusive)

  • time_attr (Symbol) —

    the time type to filter on: :modified_time, :at_time, :completed_time, :from_time or :until_time

Returns:

  • (Array<Resource>) —

    a lazy enumeration of the resources within the specified range.



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

def resources_in(time_range:, time_attr:)
  resources.select { |r| time_range.cover?(r.send(time_attr)) }
end