Class: AtlasRb::FileSet

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

Overview

An ordered, classified slot under a Work that holds a Blob.

FileSets give a Work multiple distinct files (e.g. a primary PDF, a supplemental dataset, a thumbnail) and tag each with a classification so the UI knows how to display it. The actual binary content lives on the associated Blob.

See also: Work, Blob.

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.

"/file_sets/"

Class Method Summary collapse

Methods inherited from Resource

find_many, history, mods_version, mods_versions, permissions, preview

Methods included from FaradayHelper

#connection, #multipart, #system_connection

Class Method Details

.create(id, classification, position: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil) ⇒ Hash

Create a new FileSet under a Work.

Examples:

fs = AtlasRb::FileSet.create("w-789", "primary")
AtlasRb::FileSet.update(fs["id"], "/tmp/article.pdf")

Multipage ingest — one ordered FileSet per page

page = AtlasRb::FileSet.create("w-789", "image", position: 1)
AtlasRb::FileSet.update(page["id"], "/tmp/page-001.tiff")

Retry-safe bulk-deposit create

key = SecureRandom.uuid
AtlasRb::FileSet.create("w-789", "primary", idempotency_key: key)

Parameters:

  • id (String) —

    the parent Work ID.

  • classification (String) —

    role tag for the FileSet — e.g. "primary", "supplemental", "thumbnail". The exact set is defined by the Atlas server.

  • position (Integer, nil) (defaults to: nil) —

    optional 1-based page order within the parent Work, for multipage Works (one FileSet per page). Omit for unordered FileSets — every non-multipage FileSet stays unordered. Set at create time only; Atlas stores what it is given (sequence validation — contiguity, uniqueness — is the caller's job, e.g. the Cerberus loader rejecting bad manifests before any create).

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

    optional UUID. A repeat call with the same key returns the originally-created FileSet instead of creating a new one. See Work.create for full semantics.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the created "file_set" payload, including its "id" which can then be passed to update to attach a binary, and its "position" (nil when unordered).



72
73
74
75
76
77
78
79
 
# File 'lib/atlas_rb/file_set.rb', line 72

def self.create(id, classification, position: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
  params = { work_id: id, classification: classification }
  params[:position] = position if position
  AtlasRb::Mash.new(JSON.parse(
    connection(params, nuid,
               on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
  ))["file_set"]
end

.destroy(id, nuid: nil, on_behalf_of: nil) ⇒ Faraday::Response

Delete a FileSet.

Examples:

AtlasRb::FileSet.destroy("fs-001")

Parameters:

  • id (String) —

    the FileSet ID.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Faraday::Response) —

    the raw delete response.



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

def self.destroy(id, nuid: nil, on_behalf_of: nil)
  connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
end

.find(id, nuid: nil, on_behalf_of: nil) ⇒ Hash

Fetch a single FileSet by ID.

Examples:

AtlasRb::FileSet.find("fs-001")

Parameters:

  • id (String) —

    the FileSet ID.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the "file_set" object, already unwrapped.



30
31
32
33
34
 
# File 'lib/atlas_rb/file_set.rb', line 30

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

.update(id, blob_path, nuid: nil, on_behalf_of: nil) ⇒ Hash

Attach (or replace) the binary content backing this FileSet.

The body is uploaded as application/octet-stream regardless of the file's true type — Atlas inspects the content server-side. To upload a binary blob plus an original filename, use Blob.create directly against the underlying /files/ endpoint.

Examples:

AtlasRb::FileSet.update("fs-001", "/tmp/article.pdf")

Parameters:

  • id (String) —

    the FileSet ID.

  • blob_path (String) —

    path to the binary file on disk.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the parsed JSON response from the patch.



117
118
119
120
121
122
123
124
125
 
# File 'lib/atlas_rb/file_set.rb', line 117

def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
  # Need to figure out blob vs XML
  payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                      "application/octet-stream",
                                                      File.basename(blob_path)) }
  AtlasRb::Mash.new(JSON.parse(
    multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
  ))
end