org.dataone.client

Class D1Object

java.lang.Object

org.dataone.client.D1Object

public class D1Object
extends Object

A representation of an object that can be stored in the DataONE system. Instances have fields containing both their associated data and system metadata, and are differentiated based on their ObjectFormat as stored in SystemMetadata.

Constructor Summary

Constructors

Constructor and Description
D1Object() Construct a new D1Object, which is then populated with data and system metadata during the download process.
D1Object(Identifier id, byte[] data, ObjectFormatIdentifier formatId, Subject submitter, NodeReference nodeId) Deprecated.
D1Object(Identifier id, byte[] data, String formatValue, String submitterValue, String nodeIdValue) Deprecated.
D1Object(Identifier id, DataSource data, ObjectFormatIdentifier formatId, Subject submitter, NodeReference nodeId) Create an object that contains the given data bytes and with the given system metadata values.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	checkDataIntegrity() Compares the data to the values in the size and checksum SystemMetadata fields and returns true if they match.
protected static void	checkLength(List<String> strings) Check that the all strings in the array have > 0 length.
protected static void	checkNotNull(List<Object> objects) Check if any in a list of objects are null references.
static D1Object	download(Identifier id) Contact D1 services to download the systemMetadata and data.
AccessPolicyEditor	getAccessPolicyEditor() Provides an object to manipulate this D1Object's accessPolicy
byte[]	getData() Deprecated.
DataSource	getDataSource() get the DataSource representing the data
ObjectFormatIdentifier	getFmtId() Deprecated.
ObjectFormatIdentifier	getFormatId()
Identifier	getIdentifier()
SystemMetadata	getSystemMetadata()
boolean	refreshSystemMetadata(Integer retryTimeoutMS) refresh the SystemMetadata of this object, first trying the CN, then the authoritative MN.
void	setData(byte[] data) Deprecated.
void	setDataSource(DataSource dataSource) set the DataSource representation of the data
void	setPublicAccess(Session token) Change the object to publicly readable
void	setSystemMetadata(SystemMetadata sysmeta)
protected static void	validateRequest(Identifier id, byte[] data, ObjectFormatIdentifier formatId, Subject submitter, NodeReference nodeId) Check the given set of input arguments that they are all valid and not null, and that string values are not null and of non-zero length.

Methods inherited from class java.lang.Object

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

Constructor Detail

D1Object

public D1Object()

Construct a new D1Object, which is then populated with data and system metadata during the download process.

D1Object

@Deprecated
public D1Object(Identifier id,
                   byte[] data,
                   String formatValue,
                   String submitterValue,
                   String nodeIdValue)
         throws NoSuchAlgorithmException,
                IOException,
                NotFound,
                InvalidRequest

Deprecated.

Deprecated: in favor of the constructor that uses the ObjectFormatIdentifier, Subject, and NodeReference objects instead of string value for them. Create an object that contains the given data bytes and with the given system metadata values. This constructor is used to build a D1Object locally in order to then call D1Object.create() to upload it to the proper Member Node.

Parameters:

id - the identifier of the object

data - the data bytes of the object

format - the format of the object

submitter - the submitter for the object

nodeId - the identifier of the node on which the object will be created

Throws:

NoSuchAlgorithmException - if the checksum algorithm does not exist

IOException - if the data bytes can not be read

NotFound - if the format specified is not found in the formatCache

InvalidRequest - if the content of parameters is not correct

D1Object

@Deprecated
public D1Object(Identifier id,
                   byte[] data,
                   ObjectFormatIdentifier formatId,
                   Subject submitter,
                   NodeReference nodeId)
         throws NoSuchAlgorithmException,
                IOException,
                NotFound,
                InvalidRequest

Deprecated.

Deprecated in favor of constructor that takes a DataSource Create an object that contains the given data bytes and with the given system metadata values. This constructor is used to build a D1Object locally in order to then call D1Object.create() to upload it to the proper Member Node.

Parameters:

id - the identifier of the object

data - the data bytes of the object

format - the format of the object

submitter - the submitter for the object

nodeId - the identifier of the node on which the object will be created

Throws:

NoSuchAlgorithmException - if the checksum algorithm does not exist

IOException - if the data bytes can not be read

NotFound - if the format specified is not found in the formatCache

InvalidRequest - if the content of parameters is not correct

D1Object

public D1Object(Identifier id,
        DataSource data,
        ObjectFormatIdentifier formatId,
        Subject submitter,
        NodeReference nodeId)
         throws NoSuchAlgorithmException,
                IOException,
                NotFound,
                InvalidRequest

Create an object that contains the given data bytes and with the given system metadata values. This constructor is used to build a D1Object locally in order to then call D1Object.create() to upload it to the proper Member Node.

Parameters:

id - the identifier of the object

data - the data bytes of the object

format - the format of the object

submitter - the submitter for the object

nodeId - the identifier of the node on which the object will be created

Throws:

NoSuchAlgorithmException - if the checksum algorithm does not exist

IOException - if the data bytes can not be read

NotFound - if the format specified is not found in the formatCache

InvalidRequest - if the content of parameters is not correct

Method Detail

getIdentifier

public Identifier getIdentifier()

Returns:

the identifier

getFmtId

@Deprecated
public ObjectFormatIdentifier getFmtId()

Deprecated.

Deprecated: use the method getFormatId() instead

Returns:

the type

getFormatId

public ObjectFormatIdentifier getFormatId()

Returns:

the type

getSystemMetadata

public SystemMetadata getSystemMetadata()

Returns:

the sysmeta

setSystemMetadata

public void setSystemMetadata(SystemMetadata sysmeta)
                       throws InvalidRequest

Parameters:

sysmeta - the sysmeta to set

Throws:

InvalidRequest - - if the sysmeta parameter is null

getData

public byte[] getData()
               throws IOException

Deprecated.

Deprecated in favor of the getDataSource method

Returns:

the data

Throws:

IOException

setData

public void setData(byte[] data)
             throws InvalidRequest

Deprecated.

Deprecated in favor of the setDataSource method

Parameters:

data - the data to set

Throws:

InvalidRequest - - if data parameter is null

getDataSource

public DataSource getDataSource()

get the DataSource representing the data

Returns:

Since:

v1.2

setDataSource

public void setDataSource(DataSource dataSource)

set the DataSource representation of the data

Since:

v1.2

setPublicAccess

public void setPublicAccess(Session token)
                     throws ServiceFailure,
                            InvalidToken,
                            NotFound,
                            NotAuthorized,
                            NotImplemented,
                            InvalidRequest,
                            VersionMismatch

Change the object to publicly readable

Parameters:

token - the credentials to use to make the change

Throws:

ServiceFailure

InvalidRequest

NotImplemented

NotAuthorized

NotFound

InvalidToken

VersionMismatch

download

public static D1Object download(Identifier id)
                         throws InvalidToken,
                                ServiceFailure,
                                NotAuthorized,
                                NotFound,
                                NotImplemented,
                                InsufficientResources,
                                InvalidRequest

Contact D1 services to download the systemMetadata and data. Multiple locations will be tried until the data bytes are successfully downloaded. Any exception thrown will be from the latest location checked, or from the getSystemMetadata call. Users are advised to check the integrity of the download with the checkDataIntegrity() method after the download.

Parameters:

id - identifier to be downloaded

Throws:

InvalidToken

ServiceFailure

NotAuthorized

NotFound

NotImplemented

InsufficientResources

InvalidRequest - - thrown when the data is retrieved but null

validateRequest

protected static void validateRequest(Identifier id,
                   byte[] data,
                   ObjectFormatIdentifier formatId,
                   Subject submitter,
                   NodeReference nodeId)
                               throws InvalidRequest

Check the given set of input arguments that they are all valid and not null, and that string values are not null and of non-zero length.

Parameters:

id -

data -

format -

submitter -

nodeId -

Throws:

InvalidRequest

checkNotNull

protected static void checkNotNull(List<Object> objects)
                            throws InvalidRequest

Check if any in a list of objects are null references. If so, throw an exception.

Parameters:

objects - the List of objects to check

Throws:

InvalidRequest - if any Object in the list is null

checkLength

protected static void checkLength(List<String> strings)
                           throws InvalidRequest

Check that the all strings in the array have > 0 length.

Parameters:

strings -

Throws:

InvalidRequest

checkDataIntegrity

public boolean checkDataIntegrity()
                           throws NoSuchAlgorithmException,
                                  IOException

Compares the data to the values in the size and checksum SystemMetadata fields and returns true if they match. Calculates the checksum from the data, so might be processor intensive.

Returns:

Throws:

NoSuchAlgorithmException

IOException

getAccessPolicyEditor

public AccessPolicyEditor getAccessPolicyEditor()

Provides an object to manipulate this D1Object's accessPolicy

Returns:

Since:

v1.1

refreshSystemMetadata

public boolean refreshSystemMetadata(Integer retryTimeoutMS)
                              throws InvalidToken,
                                     NotAuthorized,
                                     NotImplemented,
                                     ServiceFailure,
                                     InterruptedException

refresh the SystemMetadata of this object, first trying the CN, then the authoritative MN. Will only do the refresh if what's found on the CN or MN is more up-to-date than what's already here.

Parameters:

retryTimeoutMS - - the number of milliseconds to wait before giving up on refresh. If null, will only try the MN 1 time, otherwise will retry at regular intervals until the retryTimeout is reached.

Returns:

boolean: true if a refresh took place, otherwise false already had.

Throws:

ServiceFailure

NotImplemented

NotAuthorized

InvalidToken

InterruptedException

Since:

v1.2