org.dataone.client.v2.itk

Class DataPackage

java.lang.Object

org.dataone.client.v2.itk.DataPackage

public class DataPackage
extends Object

A DataPackage is a collection of interrelated data (science data, metadata) D1Objects plus their defined relationships (the ResourceMap object) DataPackage allows all of the science metadata, data objects, and system metadata associated with those objects to be accessed from a common place. A well-formed DataPackage contains one or more science metadata D1Objects that document one or more data D1Objects. The DataPackage relationship graph can be serialized as an OAI-ORE ResourceMap, which details the linkages among science data objects and science metadata objects. The ResourceMap is a first-class object in the DataONE object collection, the same as metadata and science data, having its own unique identifier. Retrieving a DataPackage from DataONE therefore involves first retrieving the ResourceMap, then retrieving the members individually. That is to say, the ResourceMap contains only references to the package members, not the content. DataPackage instances independently maintain 2 properties, the object map, and the relationships map. The object map maintains the local representations of the D1Objects associated with the DataPackage, and should not contain data objects not found in the relationship map. It is also used internally to access the package's data members. The relationships map determines the contents of the ResourceMap, so therefore is the ultimate authority on package membership. When creating (submitting) a new package, it is important for the object map and relationship map to be consistent. The getUnresolvableMembers() and getUncharacterizeddMembers() methods should be invoked before uploading package members and the resourceMap to a MemberNode.

Constructor Summary

Constructors

Constructor and Description
DataPackage() Default constructor without identifier.
DataPackage(Identifier id) Construct a DataPackage using the given identifier to identify this package.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAndDownloadData(Identifier id) Puts an object with the given Identifier to the package's local, temporary data store.
void	addData(D1Object obj) Puts a D1Object directly to the package's local, temporary data store without downloading it from a node.
boolean	contains(Identifier id) Determine if an object with the given Identifier is already present in the local data store.
static DataPackage	deserializePackage(String resourceMap) Deserialize an ORE resourceMap by parsing it, extracting the associated package identifier, and the list of metadata and data objects aggregated in the ORE Map.
static DataPackage	download(Identifier pid) Download the resource map
D1Object	get(Identifier id) Get the D1Object associated with a given Identifier from the local data store.
Identifier	getDocumentedBy(Identifier dataObject) Convenience function for working with the metadata map.
Map<Identifier,List<Identifier>>	getMetadataMap() Get a map of the metadata members of the resource map and the associated data they document.
Identifier	getPackageId()
org.dspace.foresite.ResourceMap	getResourceMap() Return the internally stored resource map
SystemMetadata	getSystemMetadata() Get the SystemMetadata object associated with the data package.
Set<Identifier>	getUncharacterizedMembers() Returns a list of package members that are not in the relationship map (implying that these are not true members, as they will not be included in the serialized ResourceMap).
Set<Identifier>	getUnresolvableMembers() Returns the Identifiers in the relationship map that cannot be found in the object map or resolved by the CN.
Set<Identifier>	identifiers() Return the set of Identifiers that are part of this package.
void	insertRelationship(Identifier metadataID, List<Identifier> dataIDList) Declare which data objects are documented by a metadata object, using their identifiers.
void	insertRelationship(String blankSubjectId, org.dspace.foresite.Predicate predicate, URI object) Relate a given subject blank node to an object URI using the given predicate.
void	insertRelationship(URI subject, org.dspace.foresite.Predicate predicate, List<URI> objects) Relate a given subject URI to a list of object URIs using the given predicate.
void	insertRelationship(URI subject, org.dspace.foresite.Predicate predicate, Object literal) Relate a given subject URI to a literal using the given predicate.
void	insertRelationship(URI subject, org.dspace.foresite.Predicate predicate, URI object) Relate a given subject URI to an object URI using the given predicate.
void	remove(Identifier id) Deprecated. renaming to removeData(Identifier id) for naming consistency with addData, addAndDownloadData
void	removeData(Identifier id) Removes a D1Object from the local data store based on its Identifier.
String	serializePackage() Return an ORE ResourceMap describing this package, serialized as an RDF graph.
void	setPackageId(Identifier packageId)
void	setResourceMap(org.dspace.foresite.ResourceMap resourceMap) Set the internally stored resource map
void	setSystemMetadata(SystemMetadata systemMetadata) Set the SystemMetadata object to this data package.
int	size() Used to introspect on the local temporary data store, NOT the number of DataPackage members.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataPackage

public DataPackage()

Default constructor without identifier. Identifier should be provided later using setPackageId() method

DataPackage

public DataPackage(Identifier id)

Construct a DataPackage using the given identifier to identify this package. The id is used as the identifier of the associated ORE map for this package.

Parameters:

id - the Identifier of the package

Method Detail

addAndDownloadData

public void addAndDownloadData(Identifier id)
                        throws InvalidToken,
                               ServiceFailure,
                               NotAuthorized,
                               NotFound,
                               NotImplemented,
                               InsufficientResources,
                               InvalidRequest,
                               ClientSideException

Puts an object with the given Identifier to the package's local, temporary data store. This creates a D1Object to wrap the identified object after downloading it from DataONE.

Parameters:

id - the identifier of the object to be added

Throws:

InvalidRequest

InsufficientResources

NotImplemented

NotFound

NotAuthorized

ServiceFailure

InvalidToken

ClientSideException

addData

public void addData(D1Object obj)

Puts a D1Object directly to the package's local, temporary data store without downloading it from a node. The identifier for this object is extracted from the D1Object.

Parameters:

obj - the D1Object to be added to the object map

insertRelationship

public void insertRelationship(Identifier metadataID,
                      List<Identifier> dataIDList)
                        throws org.dspace.foresite.OREException,
                               URISyntaxException

Declare which data objects are documented by a metadata object, using their identifiers. Additional calls using the same metadata identifier will append to existing data identifier lists. Identifiers used in this call will de facto be part of any serialized resource map derived from the DataPackage instance.

Parameters:

metadataID -

dataIDList -

Throws:

URISyntaxException

org.dspace.foresite.OREException

insertRelationship

public void insertRelationship(URI subject,
                      org.dspace.foresite.Predicate predicate,
                      URI object)
                        throws URISyntaxException,
                               org.dspace.foresite.OREException

Relate a given subject URI to an object URI using the given predicate. Allows general statements to be made about members of the DataPackage where both the subject and the object have resolvable URIs.

Parameters:

subject - The subject of the statement

predicate - The relationship of the statement

object - the object of the statement

Throws:

URISyntaxException

org.dspace.foresite.OREException

insertRelationship

public void insertRelationship(String blankSubjectId,
                      org.dspace.foresite.Predicate predicate,
                      URI object)
                        throws org.dspace.foresite.OREException

Relate a given subject blank node to an object URI using the given predicate. Allows properties to be set on an anonymous node in the resource map. When using this method, ensure that the subject is connected in the resource map graph.

Parameters:

blankSubjectId - The identifier used for the blank node in the resource map

predicate - the predicate of the statement

object - the URI of the object of the statement

Throws:

org.dspace.foresite.OREException

insertRelationship

public void insertRelationship(URI subject,
                      org.dspace.foresite.Predicate predicate,
                      List<URI> objects)
                        throws URISyntaxException,
                               org.dspace.foresite.OREException

Relate a given subject URI to a list of object URIs using the given predicate. Allows general statements to be made about members of the DataPackage where both the subject and the object have resolvable URIs.

Parameters:

subject - The subject of each statement

predicate - The relationship of each statement

object - the objects of each statement

Throws:

URISyntaxException

org.dspace.foresite.OREException

insertRelationship

public void insertRelationship(URI subject,
                      org.dspace.foresite.Predicate predicate,
                      Object literal)
                        throws org.dspace.foresite.OREException

Relate a given subject URI to a literal using the given predicate.

Parameters:

subject -

predicate -

literal -

Throws:

org.dspace.foresite.OREException

size

public int size()

Used to introspect on the local temporary data store, NOT the number of DataPackage members.

Returns:

the number of objects in the local temporary data store

contains

public boolean contains(Identifier id)

Determine if an object with the given Identifier is already present in the local data store.

Parameters:

id - the Identifier to be checked

Returns:

boolean true if the Identifier is in the package

get

public D1Object get(Identifier id)

Get the D1Object associated with a given Identifier from the local data store.

Parameters:

id - the identifier of the object to be retrieved

Returns:

the D1Object for that identifier, or null if not found

remove

public void remove(Identifier id)

Deprecated. renaming to removeData(Identifier id) for naming consistency with addData, addAndDownloadData

Parameters:

id -

removeData

public void removeData(Identifier id)

Removes a D1Object from the local data store based on its Identifier. Does not affect the relationship map.

Parameters:

id - the Identifier of the object to be removed.

Since:

v1.1.1

identifiers

public Set<Identifier> identifiers()

Return the set of Identifiers that are part of this package.

Returns:

a Set of Identifiers in the package

getPackageId

public Identifier getPackageId()

Returns:

the packageId

setPackageId

public void setPackageId(Identifier packageId)

Parameters:

packageId - the packageId to set

getResourceMap

public org.dspace.foresite.ResourceMap getResourceMap()

Return the internally stored resource map

Returns:

respourceMap The resource map

setResourceMap

public void setResourceMap(org.dspace.foresite.ResourceMap resourceMap)

Set the internally stored resource map

Parameters:

resourceMap - The resource map to set

serializePackage

public String serializePackage()
                        throws org.dspace.foresite.OREException,
                               URISyntaxException,
                               org.dspace.foresite.ORESerialiserException

Return an ORE ResourceMap describing this package, serialized as an RDF graph.

Returns:

the map as a serialized String

Throws:

URISyntaxException

org.dspace.foresite.OREException

org.dspace.foresite.ORESerialiserException

download

public static DataPackage download(Identifier pid)
                            throws InvalidToken,
                                   ServiceFailure,
                                   NotAuthorized,
                                   NotFound,
                                   NotImplemented,
                                   InsufficientResources,
                                   InvalidRequest,
                                   org.dspace.foresite.OREException,
                                   URISyntaxException,
                                   org.dspace.foresite.OREParserException,
                                   IOException,
                                   ClientSideException

Download the resource map

Parameters:

pid -

Returns:

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented

InsufficientResources

InvalidRequest

org.dspace.foresite.OREException

URISyntaxException

org.dspace.foresite.OREParserException

IOException

ClientSideException

deserializePackage

public static DataPackage deserializePackage(String resourceMap)
                                      throws UnsupportedEncodingException,
                                             org.dspace.foresite.OREException,
                                             URISyntaxException,
                                             org.dspace.foresite.OREParserException,
                                             InvalidToken,
                                             ServiceFailure,
                                             NotAuthorized,
                                             NotFound,
                                             NotImplemented,
                                             InsufficientResources,
                                             InvalidRequest,
                                             ClientSideException

Deserialize an ORE resourceMap by parsing it, extracting the associated package identifier, and the list of metadata and data objects aggregated in the ORE Map. Create an instance of a DataPackage, and for each metadata and data object in the aggregation, add it to the package.

Parameters:

resourceMap - the string representation of an ORE map in XML format

Returns:

DataPackage constructed from the map

Throws:

org.dspace.foresite.OREParserException

URISyntaxException

org.dspace.foresite.OREException

UnsupportedEncodingException

InvalidRequest

InsufficientResources

NotImplemented

NotFound

NotAuthorized

ServiceFailure

InvalidToken

ClientSideException

getDocumentedBy

public Identifier getDocumentedBy(Identifier dataObject)

Convenience function for working with the metadata map. Does a reverse lookup to get the metadata object that is defined to document the provided data object. Returns null if the relationship has not been defined.

Parameters:

dataObject -

Returns:

setSystemMetadata

public void setSystemMetadata(SystemMetadata systemMetadata)

Set the SystemMetadata object to this data package.

Parameters:

systemMetadata - - the SystemMetadata object will be set.

getSystemMetadata

public SystemMetadata getSystemMetadata()

Get the SystemMetadata object associated with the data package.

Returns:

the SystemMetadata object associated with the data package.

getUncharacterizedMembers

public Set<Identifier> getUncharacterizedMembers()

Returns a list of package members that are not in the relationship map (implying that these are not true members, as they will not be included in the serialized ResourceMap).

Returns:

Set : an identifier list

Since:

v1.1.1

getUnresolvableMembers

public Set<Identifier> getUnresolvableMembers()
                                       throws InvalidToken,
                                              ServiceFailure,
                                              NotImplemented

Returns the Identifiers in the relationship map that cannot be found in the object map or resolved by the CN. (Indicating that if the DataPackage is submitted as is, it will refer to non-existent objects).

Returns:

Set of unresolvable package resources

Throws:

InvalidToken

ServiceFailure

NotImplemented

Since:

v1.1.1

getMetadataMap

public Map<Identifier,List<Identifier>> getMetadataMap()

Get a map of the metadata members of the resource map and the associated data they document.

Returns:

the metadata map