Class: AtlasRb::Collection

Inherits:
Resource show all
Defined in:
lib/atlas_rb/collection.rb

Overview

A grouping of Works within a Community.

Collections are the leaf containers in the organizational tree — they hold Works directly. Every Collection has exactly one parent Community.

See also: Community, Work.

Constant Summary collapse

ROUTE =

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.

Atlas REST endpoint prefix for this resource.

"/collections/"

Class Method Summary collapse

Methods inherited from Resource

permissions, preview

Methods included from FaradayHelper

#connection, #multipart

Class Method Details

.children(id) ⇒ Array<String>

List the Works in a Collection.

The endpoint returns just the noids; resolve each through Resource.find (or Work.find) when a full payload is needed.

Examples:

AtlasRb::Collection.children("col-456")
# => ["w-789", "w-790"]

Parameters:

  • id (String) —

    the Collection ID.

Returns:

  • (Array<String>) —

    child noids from GET /collections/<id>/children.



109
110
111
 
# File 'lib/atlas_rb/collection.rb', line 109

def self.children(id)
  JSON.parse(connection({}).get(ROUTE + id + '/children')&.body)
end

.create(id, xml_path = nil) ⇒ Hash

Create a new Collection under an existing Community.

Note: unlike AtlasRb::Community.create, the id parameter here is the parent Community ID (not a parent Collection ID — Collections do not nest).

Examples:

AtlasRb::Collection.create("c-123", "/tmp/collection-mods.xml")

Parameters:

  • id (String) —

    the parent Community ID.

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

    optional path to a MODS XML file used to seed metadata. When given, the Collection is created and immediately patched with the metadata in the file.

Returns:

  • (Hash) —

    the created Collection payload (post-update if xml_path was supplied).



44
45
46
47
48
49
50
 
# File 'lib/atlas_rb/collection.rb', line 44

def self.create(id, xml_path = nil)
  result = AtlasRb::Mash.new(JSON.parse(connection({ parent_id: id }).post(ROUTE)&.body))["collection"]
  return result unless xml_path.present?

  update(result["id"], xml_path)
  find(result["id"])
end

.destroy(id) ⇒ Faraday::Response

Delete a Collection.

Examples:

AtlasRb::Collection.destroy("col-456")

Parameters:

  • id (String) —

    the Collection ID.

Returns:

  • (Faraday::Response) —

    the raw delete response.



59
60
61
 
# File 'lib/atlas_rb/collection.rb', line 59

def self.destroy(id)
  connection({}).delete(ROUTE + id)
end

.find(id) ⇒ Hash

Fetch a single Collection by ID.

Examples:

AtlasRb::Collection.find("col-456")
# => { "id" => "col-456", "title" => "Faculty Publications", ... }

Parameters:

  • id (String) —

    the Collection ID.

Returns:

  • (Hash) —

    the "collection" object, already unwrapped from the JSON response.



25
26
27
 
# File 'lib/atlas_rb/collection.rb', line 25

def self.find(id)
  AtlasRb::Mash.new(JSON.parse(connection({}).get(ROUTE + id)&.body))["collection"]
end

.metadata(id, values) ⇒ Hash

Patch individual metadata fields without uploading a full MODS document.

Examples:

AtlasRb::Collection.metadata("col-456", title: "Renamed Collection")

Parameters:

  • id (String) —

    the Collection ID.

  • values (Hash) —

    field-level metadata updates.

Returns:

  • (Hash) —

    the parsed JSON response.



136
137
138
 
# File 'lib/atlas_rb/collection.rb', line 136

def self.metadata(id, values)
  AtlasRb::Mash.new(JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body))
end

.mods(id, kind = nil) ⇒ String

Fetch the Collection's MODS representation in the requested format.

Examples:

AtlasRb::Collection.mods("col-456", "xml")

Parameters:

  • id (String) —

    the Collection ID.

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

    one of "json" (default), "html", or "xml".

Returns:

  • (String) —

    the raw response body in the requested format.



149
150
151
152
153
154
 
# File 'lib/atlas_rb/collection.rb', line 149

def self.mods(id, kind = nil)
  # json default, html, xml
  connection({}).get(
    ROUTE + id + '/mods' + (kind.present? ? ".#{kind}" : '')
    )&.body
end

.restore(id, nuid:) ⇒ Faraday::Response

Restore a previously tombstoned Collection.

Operator-only. Restoration is intentionally not exposed in any end-user UI; call this from a Rails console session (or a future admin panel) when the library has decided an object should come back.

Examples:

Operator restoring from bundle exec rails console

AtlasRb::Collection.restore("col-456", nuid: "000000002")

Parameters:

  • id (String) —

    the Collection ID.

  • nuid (String) —

    the acting user's NUID.

Returns:

  • (Faraday::Response) —

    the raw response.



94
95
96
 
# File 'lib/atlas_rb/collection.rb', line 94

def self.restore(id, nuid:)
  connection({}, nuid).post(ROUTE + id + '/restore')
end

.tombstone(id, nuid:) ⇒ Faraday::Response

Tombstone (withdraw) a Collection.

The Collection remains in Atlas storage but is marked as withdrawn: search and show pages return a withdrawn stub for every user. Atlas rejects the request with 422 has_live_children if the Collection still has live (non-tombstoned) Works.

Examples:

AtlasRb::Collection.tombstone("col-456", nuid: "000000002")

Parameters:

  • id (String) —

    the Collection ID.

  • nuid (String) —

    the acting user's NUID, stamped on the resource as tombstoned_by for audit purposes.

Returns:

  • (Faraday::Response) —

    the raw response. 200/204 on success; 422 with {"code":"has_live_children"} if the Collection is not empty.



78
79
80
 
# File 'lib/atlas_rb/collection.rb', line 78

def self.tombstone(id, nuid:)
  connection({}, nuid).post(ROUTE + id + '/tombstone')
end

.update(id, xml_path) ⇒ Hash

Replace a Collection's metadata by uploading a MODS XML document.

Examples:

AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml")

Parameters:

  • id (String) —

    the Collection ID.

  • xml_path (String) —

    path to a MODS XML file on disk.

Returns:

  • (Hash) —

    the parsed JSON response from the patch.



121
122
123
124
125
126
 
# File 'lib/atlas_rb/collection.rb', line 121

def self.update(id, xml_path)
  payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                       "application/xml",
                                                       File.basename(xml_path)) }
  AtlasRb::Mash.new(JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body))
end