org.dataone.client

Class DataPackage

java.lang.Object

org.dataone.client.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.
org.dspace.foresite.ResourceMap	getMap() Build and return a fresh ORE ResourceMap from the metadata map.
Map<Identifier,List<Identifier>>	getMetadataMap()
Identifier	getPackageId()
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	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	setMetadataMap(Map<Identifier,List<Identifier>> metadataMap)
void	setPackageId(Identifier packageId)
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

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

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)

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 -

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

getMap

public org.dspace.foresite.ResourceMap getMap()
                                       throws org.dspace.foresite.OREException,
                                              URISyntaxException

Build and return a fresh ORE ResourceMap from the metadata map. TODO: create a RM when science metadata is null TODO: handle error conditions when data list is null

Returns:

the map

Throws:

URISyntaxException

org.dspace.foresite.OREException

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

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

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

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

getMetadataMap

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

Returns:

the metadata map

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:

setMetadataMap

public void setMetadataMap(Map<Identifier,List<Identifier>> metadataMap)

Parameters:

metadataMap - the metadataMap to set

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