Package com.dnanexus

Class DXDataObject

java.lang.Object

com.dnanexus.DXObject

com.dnanexus.DXDataObject

Direct Known Subclasses:

DXApplet, DXFile, DXRecord, DXWorkflow

public abstract class DXDataObject
extends DXObject

Base class for all data object classes in the DNAnexus Platform.

Instances of this class are JSON-serialized as a DNAnexus link, which makes it suitable to provide an object with references to DXDataObjects as the input when running a DXApplet, etc.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	DXDataObject.Builder<T extends DXDataObject.Builder<T,U>,U extends DXDataObject>	Abstract builder class for creating a new data object of class U.
static class	DXDataObject.Describe	Contains metadata for a data object (fields common to all data objects).
static class	DXDataObject.DescribeOptions	Configuration options for a describe call on a data object (e.g. describe(DescribeOptions)) to control what optional fields get returned and what project to obtain project-specific metadata from.

Field Summary

Fields

Modifier and Type	Field	Description
protected com.fasterxml.jackson.databind.JsonNode	cachedDescribe

Fields inherited from class com.dnanexus.DXObject

dxId, env, MAPPER

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	DXDataObject(String dxId, String className, DXContainer project, DXEnvironment env, com.fasterxml.jackson.databind.JsonNode cachedDescribe)	Initializes the DXDataObject to point to the object with the specified ID in the specified project.
protected	DXDataObject(String dxId, String className, DXEnvironment env, com.fasterxml.jackson.databind.JsonNode cachedDescribe)	Initializes the DXDataObject to point to the object with the specified ID in the environment's workspace.

Method Summary

Modifier and Type	Method	Description
void	addTags(List<String> tags)	Adds the specified tags to the object.
void	addTypes(List<String> types)	Adds the specified types to the object.
protected void	checkCachedDescribeAvailable()	Verifies that this object carries cached describe data.
protected static void	checkDXLinkFormat(Map<String,Object> value)	Verifies that the specified map has the format of a DNAnexus link.
DXDataObject	close()	Closes the data object.
DXDataObject	closeAndWait()	Closes the data object and waits until the close operation is complete.
DXDataObject.Describe	describe()	Returns metadata about the data object.
DXDataObject.Describe	describe(DXDataObject.DescribeOptions options)	Returns metadata about the data object, specifying which optional fields are to be returned and what project to obtain project-specific metadata from.
boolean	equals(Object obj)
DXDataObject.Describe	getCachedDescribe()	Returns metadata about the data object, like describe(), but without making an API call.
static DXDataObject	getInstance(String objectId)	Returns a DXDataObject corresponding to an existing object with the specified ID.
static DXDataObject	getInstance(String objectId, DXContainer project)	Returns a DXDataObject corresponding to an existing object with the specified ID in the specified project or container.
static DXDataObject	getInstanceWithEnvironment(String objectId, DXContainer project, DXEnvironment env)	Returns a DXDataObject corresponding to an existing object with the specified ID in the specified project or container, using the specified environment.
static DXDataObject	getInstanceWithEnvironment(String objectId, DXEnvironment env)	Returns a DXDataObject corresponding to an existing object with the specified ID, using the specified environment.
com.fasterxml.jackson.databind.JsonNode	getLinkAsJson()	Returns a DNAnexus link for this object.
DXContainer	getProject()	Returns the object's project or container, if it was explicitly supplied.
int	hashCode()
Map<DXContainer,AccessLevel>	listProjects()	Returns the set of projects that contain this object, and which the requesting user has permissions to access.
void	putAllProperties(Map<String,String> properties)	Sets properties on the object.
void	putAllProperties(Map<String,String> propertiesToSet, List<String> propertiesToRemove)	Sets and removes properties on the object.
void	putProperty(String key, String value)	Sets a property on the object.
void	removeProperty(String key)	Removes a property from the object.
void	removeTags(List<String> tags)	Removes the specified tags from the object.
void	removeTypes(List<String> types)	Removes the specified types from the object.
void	rename(String newName)	Changes the name of the object in its project.
void	setDetails(Object details)	Sets the details of the object.
void	setVisibility(boolean visible)	Makes the object visible or hidden.

Methods inherited from class com.dnanexus.DXObject

apiCallOnObject, apiCallOnObject, getId, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

cachedDescribe

protected final com.fasterxml.jackson.databind.JsonNode cachedDescribe

Constructor Detail

DXDataObject

protected DXDataObject(String dxId,
                       String className,
                       DXContainer project,
                       DXEnvironment env,
                       com.fasterxml.jackson.databind.JsonNode cachedDescribe)

Initializes the DXDataObject to point to the object with the specified ID in the specified project.

Parameters:

dxId - DNAnexus ID of the data object

className - class name that should prefix the ID

env - environment to use for subsequent API requests from this DXDataObject, or null to use the default environment

cachedDescribe - JSON hash of the describe output for this object if available, or null otherwise

DXDataObject

protected DXDataObject(String dxId,
                       String className,
                       DXEnvironment env,
                       com.fasterxml.jackson.databind.JsonNode cachedDescribe)

Initializes the DXDataObject to point to the object with the specified ID in the environment's workspace.

Operations that use or retrieve project-specific metadata will fail if the object does not exist in the environment's workspace. When a project is available, you should prefer to set it explicitly via DXDataObject(String, String, DXContainer, DXEnvironment, JsonNode) .

Parameters:

dxId - DNAnexus ID of the data object

className - class name that should prefix the ID

env - environment to use for subsequent API requests from this DXDataObject, or null to use the default environment

cachedDescribe - JSON hash of the describe output for this object if available, or null otherwise

Method Detail

checkDXLinkFormat

protected static void checkDXLinkFormat(Map<String,Object> value)

Verifies that the specified map has the format of a DNAnexus link.

Parameters:

value - putative DNAnexus link

getInstance

public static DXDataObject getInstance(String objectId)

Returns a DXDataObject corresponding to an existing object with the specified ID.

Parameters:

objectId - DNAnexus object id

Returns:

a DXDataObject handle to the specified object

getInstance

public static DXDataObject getInstance(String objectId,
                                       DXContainer project)

Returns a DXDataObject corresponding to an existing object with the specified ID in the specified project or container.

Parameters:

objectId - DNAnexus object id

project - project or container in which the object resides

Returns:

a DXDataObject handle to the specified object

getInstanceWithEnvironment

public static DXDataObject getInstanceWithEnvironment(String objectId,
                                                      DXContainer project,
                                                      DXEnvironment env)

Returns a DXDataObject corresponding to an existing object with the specified ID in the specified project or container, using the specified environment.

Parameters:

objectId - DNAnexus object id

project - project or container in which the object resides

env - environment to use to make subsequent API requests

Returns:

a DXDataObject handle to the specified object

getInstanceWithEnvironment

public static DXDataObject getInstanceWithEnvironment(String objectId,
                                                      DXEnvironment env)

Returns a DXDataObject corresponding to an existing object with the specified ID, using the specified environment.

Parameters:

objectId - DNAnexus object id

env - environment to use to make subsequent API requests

Returns:

a DXDataObject handle to the specified object

addTags

public void addTags(List<String> tags)

Adds the specified tags to the object.

The tags are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

tags - List of tags to add to the object

Throws:

NullPointerException - if this object has no associated project and no workspace is set

addTypes

public void addTypes(List<String> types)

Adds the specified types to the object.

Parameters:

types - List of types to add to the object

checkCachedDescribeAvailable

protected void checkCachedDescribeAvailable()
                                     throws IllegalStateException

Verifies that this object carries cached describe data.

Throws:

IllegalStateException - if cachedDescribe is not set.

close

public DXDataObject close()

Closes the data object.

Returns the same object so you can chain calls.

Returns:

the same DXDataObject

closeAndWait

public DXDataObject closeAndWait()

Closes the data object and waits until the close operation is complete.

Returns the same object so you can chain calls.

Returns:

the same DXDataObject

describe

public DXDataObject.Describe describe()

Returns metadata about the data object.

The properties and details fields will not be returned, and any project-specific metadata fields will be selected from an arbitrary project in which the requesting user has access to this object. To change either of these aspects of this behavior, use describe(DescribeOptions) instead.

Returns:

a Describe containing the data object's metadata.

describe

public DXDataObject.Describe describe(DXDataObject.DescribeOptions options)

Returns metadata about the data object, specifying which optional fields are to be returned and what project to obtain project-specific metadata from.

Parameters:

options - DescribeOptions object specifying how the describe request is to be made.

Returns:

a Describe containing the data object's metadata.

equals

public boolean equals(Object obj)

Overrides:

equals in class DXObject

getCachedDescribe

public DXDataObject.Describe getCachedDescribe()

Returns metadata about the data object, like describe(), but without making an API call.

This cached describe info is only available if this object appears in the result of a DXSearch.findDataObjects() call that specified DXSearch.FindDataObjectsRequestBuilder.includeDescribeOutput(), and the describe info that is returned reflects the state of the object at the time that the search was performed.

Returns:

a Describe containing the data object's metadata

Throws:

IllegalStateException - if no cached describe info is available

getLinkAsJson

public com.fasterxml.jackson.databind.JsonNode getLinkAsJson()

Returns a DNAnexus link for this object.

Returns:

a DNAnexus link

getProject

public DXContainer getProject()

Returns the object's project or container, if it was explicitly supplied.

Returns:

project or container, or null if none was specified at object creation time

hashCode

public int hashCode()

Overrides:

hashCode in class DXObject

listProjects

public Map<DXContainer,AccessLevel> listProjects()

Returns the set of projects that contain this object, and which the requesting user has permissions to access.

Returns:

Mapping from project ID to the user's access level in that project.

putAllProperties

public void putAllProperties(Map<String,String> properties)

Sets properties on the object.

The properties are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

properties - Map from key to value for each property to be set

Throws:

NullPointerException - if this object has no associated project and no workspace is set

putAllProperties

public void putAllProperties(Map<String,String> propertiesToSet,
                             List<String> propertiesToRemove)

Sets and removes properties on the object.

The properties are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

propertiesToSet - Map from key to value for each property to be set

propertiesToRemove - List of property keys to be removed

Throws:

NullPointerException - if this object has no associated project and no workspace is set

putProperty

public void putProperty(String key,
                        String value)

Sets a property on the object.

The properties are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

key - property key to set

value - property value to set

Throws:

NullPointerException - if this object has no associated project and no workspace is set

removeProperty

public void removeProperty(String key)

Removes a property from the object.

The properties are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

key - property key to be removed

Throws:

NullPointerException - if this object has no associated project and no workspace is set

removeTags

public void removeTags(List<String> tags)

Removes the specified tags from the object.

The tags are modified in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

tags - List of tags to remove

Throws:

NullPointerException - if this object has no associated project and no workspace is set

removeTypes

public void removeTypes(List<String> types)

Removes the specified types from the object.

Parameters:

types - List of types to remove

rename

public void rename(String newName)

Changes the name of the object in its project. The basename of the object is changed to the specified name and it remains in the same folder.

The object is renamed in the project or container associated with this DXDataObject, or the environment's workspace if no project or container was explicitly specified.

Parameters:

newName - The new name of the object

Throws:

NullPointerException - if this object has no associated project and no workspace is set

setDetails

public void setDetails(Object details)

Sets the details of the object.

Parameters:

details - an object whose JSON serialized form will be set as the details

setVisibility

public void setVisibility(boolean visible)

Makes the object visible or hidden.

Parameters:

visible -