Class: AtlasRb::Community

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

Overview

A top-level grouping in the Atlas hierarchy.

Communities are organizational containers — they hold Collections and, optionally, sub-Communities. Most institutional structure (departments, programs, projects) is modeled as a tree of Communities with Collections at the leaves.

See also: Collection, 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.

"/communities/"

Constants inherited from Resource

Resource::TYPE_MAP

Constants included from FaradayHelper

FaradayHelper::ASSERTION_AUDIENCE, FaradayHelper::ASSERTION_ISSUER, FaradayHelper::ASSERTION_TTL, FaradayHelper::INSTRUMENTATION_EVENT

Class Method Summary collapse

Methods inherited from Resource

class_for, descendant_works, find_many, history, mods_version, mods_versions, permissions, preview, put_mods, reparent, set_permissions, set_thumbnails, tombstone

Methods included from FaradayHelper

#connection, #multipart, #read_body, #read_raw, #system_connection, #with_file_part

Class Method Details

.children(id, nuid: nil, on_behalf_of: nil) ⇒ Array<String>?

List the immediate children (sub-Communities and Collections) of a Community.

The endpoint returns just the noids; resolve each through Resource.find (which dispatches by type) when richer payloads are needed.

children answers noids only. To render them, resolve the whole list in one call with Resource.find_many, which returns a title/thumbnail digest per id — calling find per noid costs a round-trip per child. For a whole subtree flattened to Works, use Resource.descendant_works.

Examples:

AtlasRb::Community.children("c-123")
# => ["fn106x926", "kw52j804p"]

Parameters:

  • id (String) —

    the parent Community ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

  • 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:

  • (Array<String>, nil) —

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

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



120
121
122
 
# File 'lib/atlas_rb/community.rb', line 120

def self.children(id, nuid: nil, on_behalf_of: nil)
  read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
end

.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil, depositor: nil) ⇒ Hash

Create a new Community, optionally seeded with MODS metadata.

Pass id = nil to create a top-level Community; pass a Community ID to nest the new Community beneath an existing one.

Examples:

Top-level community, no metadata

AtlasRb::Community.create(nil)

Sub-community seeded from MODS

AtlasRb::Community.create("c-parent", "/tmp/dept-mods.xml")

An institutional container owned by nobody

AtlasRb::Community.create("c-parent", depositor: "000000099")

Parameters:

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

    the parent Community ID, or nil for a top-level Community.

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

    optional path to a MODS XML file. When given, the Community is created and immediately patched with the metadata in the file; the returned Hash reflects the patched state.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

  • 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.

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

    NUID to stamp as the Community's intellectual owner. Omit it and Atlas falls through to the acting user. Supply it to attribute a container to someone other than whoever is authorizing the call — e.g. seeding an institutional tree as an admin while attributing it to the anonymous NUID, since nobody personally owns those containers and access to them is via Grouper groups. The depositor is immutable post-create; there is no setter on the update surface.

Returns:

  • (Hash) —

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

Raises:



77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/atlas_rb/community.rb', line 77

def self.create(id = nil, xml_path = nil, nuid: nil, on_behalf_of: nil, depositor: nil)
  params = { parent_id: id }
  params[:depositor] = depositor if depositor
  result = AtlasRb::Mash.new(write_resource(
    connection(params, nuid, on_behalf_of: on_behalf_of).post(ROUTE)
  ))["community"]
  return result if xml_path.to_s.empty?

  # The MODS seed is a second call: create takes the parent and the
  # provenance slots, and the document goes through the write that owns it.
  AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
  find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
end

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

Fetch a single Community by ID.

Examples:

AtlasRb::Community.find("c-123")
# => { "id" => "c-123", "title" => "College of Engineering", ... }

Parameters:

  • id (String) —

    the Community ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

  • 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, nil) —

    the "community" object from the JSON response, already unwrapped, or nil when the Community does not exist (404).

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (e.g. an auth/validation error envelope), carrying Atlas's status + body.



34
35
36
37
 
# File 'lib/atlas_rb/community.rb', line 34

def self.find(id, nuid: nil, on_behalf_of: nil)
  body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
  body && AtlasRb::Mash.new(body)["community"]
end

.mods(id, kind = nil, nuid: nil, on_behalf_of: nil) ⇒ String?

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

Examples:

HTML rendering for display

AtlasRb::Community.mods("c-123", "html")

Parameters:

  • id (String) —

    the Community ID.

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

    one of "json" (default when omitted), "html", or "xml". When nil, Atlas returns its default representation.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

  • 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:

  • (String, nil) —

    the raw response body (JSON, HTML, or XML serialized as a string).

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



146
147
148
149
150
151
 
# File 'lib/atlas_rb/community.rb', line 146

def self.mods(id, kind = nil, nuid: nil, on_behalf_of: nil)
  # json default, html, xml
  read_raw(connection({}, nuid, on_behalf_of: on_behalf_of).get(
             ROUTE + id + '/mods' + (kind.to_s.empty? ? '' : ".#{kind}")
           ))
end