Class: ResourceMap

ResourceMap(options)

Read, edit, validate, and serialize one DataONE Resource Map. A Resource Map is an RDF document that lists a package's members and describes relationships among them. This class stores the normalized RDF graph, including membership, links from metadata to data, locations, creator and modified values, and package history. Callers should edit through ResourceMap methods so cached package summaries stay in sync. Imported graphs are repaired only when the graph determines the intended statement without guessing. The graph remains the source of truth. `getSummary()` gives the UI a simpler view that cannot change the graph. Import converts configured endpoint URLs to CN resolver URLs when their identifiers agree. Foreign URLs, conflicting destinations, and `prov:atLocation` targets are preserved. Map and aggregation identities change only when `setResourceMapPid()` assigns a new version.

Constructor

new ResourceMap(options)

Parameters:
Name Type Description
options object Constructor options
Properties
Name Type Attributes Description
resourceMapPid string DataONE PID for the resource map object
resolveServiceUrl string CN resolve endpoint for new nodes and URLs converted during import
objectServiceUrl string <optional>
 Object service base used to recognize managed endpoint URLs during import
graph IndexedFormula | RDFGraph <optional>
 Existing RDF graph to adopt. Used when constructing a ResourceMap from parsed RDF/XML
Since:
  • 2.39.0
Source:

Members

pendingEndpointNodes :Array.<NamedNode>

Identified endpoint nodes waiting for the grouped edit to finish.
Type:
  • Array.<NamedNode>
Since:
  • 2.41.0
Source:

Methods

addLocation(pid, path) → {ResourceMap}

Add one source location or path to a package member.
Parameters:
Name Type Description
pid string Aggregated member PID
path string Raw location value
Source:
Returns:
Updated resource map
Type
ResourceMap

ensureIdentifierForUri(uri, pid) → {ResourceMap}

Add the DataONE PID identifier to an RDF resource if it is missing.
Parameters:
Name Type Description
uri string RDF subject URI
pid string DataONE PID
Source:
Returns:
Updated resource map
Type
ResourceMap
Source:
Returns:
Links from metadata to documented data.
Type
Array.<ResMapDocLink>

getEditBlockers() → {Array.<object>}

Return only validation errors that block editing and validated output.
Source:
Returns:
Error severity validation issues
Type
Array.<object>

getMemberPids() → {Array.<string>}

Source:
Returns:
Aggregated member PIDs.
Type
Array.<string>

getNodeUriForPid(pid) → {string}

Return the URI already used for a PID, or create its configured resolve URI when the graph does not contain one.
Parameters:
Name Type Description
pid string PID whose current RDF subject URI should be resolved.
Source:
Returns:
Existing graph URI or configured resolve URI.
Type
string

getSummary() → {ResourceMapSummary}

Return a plain package summary built from the RDF graph.
Source:
Returns:
Package summary
Type
ResourceMapSummary

hasUnsavedChanges() → {boolean}

Source:
Returns:
Whether the graph has changed since loading or save.
Type
boolean

isGraphMutating() → {boolean}

Source:
Returns:
Whether a grouped graph mutation is in progress.
Type
boolean

linkDocumentation(metadataPid, dataPid) → {ResourceMap}

Record in both directions that a metadata member documents a data member.
Parameters:
Name Type Description
metadataPid string Documenting metadata PID.
dataPid string Documented member PID.
Source:
Returns:
Updated resource map.
Type
ResourceMap

markSaved() → {ResourceMap}

Source:
Returns:
Resource map with a cleared dirty flag.
Type
ResourceMap

mutateGraph(mutator, optionsopt) → {ResourceMap}

Apply one grouped RDF edit while keeping cached summaries, change tracking, and optional rollback consistent. Use this only when the public ResourceMap methods cannot express the edit.
Parameters:
Name Type Attributes Description
mutator function Graph mutation callback.
options object <optional>
 Mutation bookkeeping options. Graph mutations that affect derived JSON reads should flow through this method or other `ResourceMap` APIs so the cached summary stays coherent
Properties
Name Type Attributes Description
markDirty boolean <optional>
 Mark a successful outer mutation unsaved. When false, preserve the previous dirty state.
rollbackOnError boolean <optional>
 Restore the graph if the outermost mutation throws.
Source:
Throws:
When the mutation callback fails
Type
Error
Returns:
Updated resource map instance.
Type
ResourceMap

normalize(optionsopt) → {ResourceMap}

Repair missing or duplicate package statements only when the graph makes the intended value certain.
Parameters:
Name Type Attributes Description
options object <optional>
 Normalization options.
Properties
Name Type Attributes Description
markDirty boolean <optional>
 Mark normalization changes unsaved.
Source:
Throws:
When the graph no longer contains the same Resource Map document and aggregation selected during construction.
Type
ResourceMapConflictError
Returns:
Updated resource map instance.
Type
ResourceMap

pidToUri(pid) → {string}

Convert a PID into its URI under the configured DataONE resolve service.
Parameters:
Name Type Description
pid string PID to encode as a resolve service URI.
Source:
Returns:
Canonical resolve URI for the PID.
Type
string

removeLocation(pid, pathopt) → {ResourceMap}

Remove one matching location, or every location when no path is given.
Parameters:
Name Type Attributes Description
pid string Member PID.
path string <optional>
 Specific raw location value to remove.
Source:
Returns:
Updated resource map.
Type
ResourceMap

removeMembers(pids) → {ResourceMap}

Remove package members and managed relationships attached to their exact RDF nodes.
Parameters:
Name Type Description
pids Array.<string> PIDs to remove
Source:
Returns:
Updated resource map
Type
ResourceMap

replaceMember(oldPid, newPid) → {ResourceMap}

Change a package member's PID wherever managed package relationships use it.
Parameters:
Name Type Description
oldPid string Existing member PID
newPid string Replacement member PID
Source:
Throws:
When the replacement PID is already aggregated or its destination node has conflicting identity.
Type
ResourceMapConflictError
Returns:
Updated resource map
Type
ResourceMap

resolveMemberNode(pid, optionsopt) → {Object|null}

Find the single exact RDF node representing a package member. Return `null` when the PID is not a member, and reject multiple matching member nodes instead of guessing.
Parameters:
Name Type Attributes Description
pid string Member PID to inspect
options object <optional>
 Resolution options
Properties
Name Type Attributes Description
required boolean <optional>
 Throw when the PID is not a package member
message string <optional>
 Missing/invalid PID error prefix
Source:
Throws:
When multiple exact member URIs claim the PID
Type
ResourceMapConflictError
Returns:
Sole exact membership node, when present
Type
Object | null

serialize(optionsopt) → {string}

Convert the current graph to RDF/XML, optionally rejecting validation errors first.
Parameters:
Name Type Attributes Description
options object <optional>
 Serialization options.
Properties
Name Type Attributes Description
validate boolean <optional>
 Throw when validation errors remain in the current graph.
Source:
Throws:
When validation is requested and the graph is invalid
Type
Error
Returns:
RDF/XML serialization of the current graph.
Type
string
Replace all links from metadata to documented data.
Parameters:
Name Type Description
links Array.<ResMapDocLink> Desired documentation links.
Source:
Returns:
Updated resource map.
Type
ResourceMap

setIdentifierForUri(uri, pid, optionsopt) → {ResourceMap}

Add a DataONE PID identifier and remove specified obsolete identifiers from an RDF resource.
Parameters:
Name Type Attributes Description
uri string RDF subject URI
pid string DataONE PID
options object <optional>
 Identifier update options
Properties
Name Type Attributes Description
removeValues Array.<string> <optional>
 Identifier values to remove
Source:
Returns:
Updated resource map
Type
ResourceMap

setLocation(pid, path) → {ResourceMap}

Replace the stored source location or path for one member.
Parameters:
Name Type Description
pid string Aggregated member PID
path string Raw location value
Source:
Returns:
Updated resource map
Type
ResourceMap

setMemberLocations(locationUpdates) → {ResourceMap}

Replace the stored source locations or paths for multiple members.
Parameters:
Name Type Description
locationUpdates Array.<{pid: string, atLocations: Array.<string>}> Member location updates. An empty `atLocations` array clears locations
Source:
Returns:
Updated resource map
Type
ResourceMap

setModified(modified) → {ResourceMap}

Set the resource map modified timestamp.
Parameters:
Name Type Description
modified string | Date ISO timestamp or `Date`.
Source:
Returns:
Updated resource map instance.
Type
ResourceMap

setPackageStructure(pids, links) → {ResourceMap}

Set all package members and metadata documentation links in one edit. If any step fails, the whole edit is rolled back.
Parameters:
Name Type Description
pids Array.<string> Desired member PIDs
links Array.<ResMapDocLink> Desired documentation links
Source:
Returns:
Updated resource map
Type
ResourceMap

setResourceMapPid(pid) → {ResourceMap}

Change the Resource Map PID and update the map and package URIs that depend on it.
Parameters:
Name Type Description
pid string Replacement PID for the resource map object.
Source:
Returns:
Updated resource map instance.
Type
ResourceMap

unlinkDocumentation(metadataPid, dataPid) → {ResourceMap}

Remove both RDF directions of a link from metadata to documented data.
Parameters:
Name Type Description
metadataPid string Documenting metadata PID.
dataPid string Documented member PID.
Source:
Returns:
Updated resource map.
Type
ResourceMap

validate() → {Array.<object>}

Check whether the Resource Map can be edited and published safely.
Source:
Returns:
Validation issues.
Type
Array.<object>

create(optionsopt) → {ResourceMap}

Create a new Resource Map from a list of members and package relationships.
Parameters:
Name Type Attributes Description
options object <optional>
 Structured package values used to seed the graph.
Properties
Name Type Attributes Description
resourceMapPid string <optional>
 PID assigned to the resource map object. A generated PID is used when omitted.
resolveServiceUrl string Resolve service base URL used to create member URIs
objectServiceUrl string <optional>
 Object service base used only to recognize exact managed URLs
members Array.<ResourceMapCreateMember> <optional>
 Package members and their optional original storage locations or paths.
memberPids Array.<string> <optional>
 Convenience shorthand for a plain list of member PIDs without `prov:atLocation` values. Any PID already present in `members` is ignored.
documentationLinks Array.<ResMapDocLink> <optional>
 Links from metadata to documented data
creatorName string <optional>
 Creator name to write onto the map.
modified string | Date <optional>
 Modified timestamp to store in the format of an xsd:dateTime literal, e.g. `2024-01-01T12:00:00Z`.
Source:
Returns:
Newly created resource map instance.
Type
ResourceMap

defaultFileName(pid) → {string}

Build the default upload filename for a resource map PID.
Parameters:
Name Type Description
pid string Resource map PID
Source:
Returns:
Resource map filename
Type
string

fromXml(resourceMapPid, resourceMapXml, options) → {ResourceMap}

Parse RDF/XML and repair unambiguous package statements and configured endpoint URLs. Import repairs do not mark the model unsaved.
Parameters:
Name Type Description
resourceMapPid string PID expected for the resource map object
resourceMapXml string RDF/XML serialization
options object Parse options
Properties
Name Type Attributes Description
resolveServiceUrl string CN resolve endpoint for new nodes and URLs converted during import
objectServiceUrl string <optional>
 Current object service base used only to recognize exact managed URLs
Source:
Throws:
When required input is missing or the RDF/XML is invalid
Type
Error
Returns:
Parsed resource map instance
Type
ResourceMap