com.dnanexus

Class DXFile

java.lang.Object

com.dnanexus.DXObject

com.dnanexus.DXDataObject

com.dnanexus.DXFile

public class DXFile
extends DXDataObject

A file (an opaque sequence of bytes).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DXFile.Builder Builder class for creating a new DXFile object.
static class	DXFile.Describe Contains metadata for a file.

Nested classes/interfaces inherited from class com.dnanexus.DXDataObject

DXDataObject.DescribeOptions

Field Summary

Fields inherited from class com.dnanexus.DXDataObject

cachedDescribe

Fields inherited from class com.dnanexus.DXObject

dxId, env, MAPPER

Method Summary

Modifier and Type	Method and Description
DXFile	close() Closes the data object.
DXFile	closeAndWait() Closes the data object and waits until the close operation is complete.
DXFile.Describe	describe() Returns metadata about the data object.
DXFile.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.
byte[]	downloadBytes() Downloads the entire file into a byte array.
byte[]	downloadBytes(long start, long end) Downloads the specified byte range of the file into a byte array.
void	downloadToOutputStream(OutputStream os) Downloads the entire file and writes the data to an OutputStream.
void	downloadToOutputStream(OutputStream os, long start, long end) Downloads the specified byte range of the file into an OutputStream.
DXFile.Describe	getCachedDescribe() Returns metadata about the data object, like DXDataObject.describe(), but without making an API call.
InputStream	getDownloadStream() Returns a stream of the file's contents.
InputStream	getDownloadStream(long start, long end) Returns a stream of the specified byte range of the file's contents.
static DXFile	getInstance(String fileId) Returns a DXFile associated with an existing file.
static DXFile	getInstance(String fileId, DXContainer project) Returns a DXFile associated with an existing file in a particular project or container.
static DXFile	getInstanceWithEnvironment(String fileId, DXContainer project, DXEnvironment env) Returns a DXFile associated with an existing file in a particular project using the specified environment.
static DXFile	getInstanceWithEnvironment(String fileId, DXEnvironment env) Returns a DXFile associated with an existing file using the specified environment.
OutputStream	getUploadStream() Returns an OutputStream that uploads any data written to it
static DXFile.Builder	newFile() Returns a Builder object for creating a new DXFile.
static DXFile.Builder	newFileWithEnvironment(DXEnvironment env) Returns a Builder object for creating a new DXFile using the specified environment.
void	upload(byte[] data) Uploads data from the specified byte array to the file.
void	upload(InputStream data) Uploads data from the specified stream to the file.

Methods inherited from class com.dnanexus.DXDataObject

addTags, addTypes, checkCachedDescribeAvailable, checkDXLinkFormat, equals, getLinkAsJson, getProject, hashCode, listProjects, putAllProperties, putAllProperties, putProperty, removeProperty, removeTags, removeTypes, rename, setDetails, setVisibility

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

Method Detail

getInstance

public static DXFile getInstance(String fileId)

Returns a DXFile associated with an existing file.

Throws:

NullPointerException - If fileId is null

getInstance

public static DXFile getInstance(String fileId,
                                 DXContainer project)

Returns a DXFile associated with an existing file in a particular project or container.

Throws:

NullPointerException - If fileId or container is null

getInstanceWithEnvironment

public static DXFile getInstanceWithEnvironment(String fileId,
                                                DXContainer project,
                                                DXEnvironment env)

Returns a DXFile associated with an existing file in a particular project using the specified environment.

Throws:

NullPointerException - If fileId or container is null

getInstanceWithEnvironment

public static DXFile getInstanceWithEnvironment(String fileId,
                                                DXEnvironment env)

Returns a DXFile associated with an existing file using the specified environment.

Throws:

NullPointerException - If fileId is null

newFile

public static DXFile.Builder newFile()

Returns a Builder object for creating a new DXFile.

Returns:

a newly initialized builder object

newFileWithEnvironment

public static DXFile.Builder newFileWithEnvironment(DXEnvironment env)

Returns a Builder object for creating a new DXFile using the specified environment.

Parameters:

env - environment to use to make API calls

Returns:

a newly initialized builder object

close

public DXFile close()

Description copied from class: DXDataObject

Closes the data object.

Returns the same object so you can chain calls.

Overrides:

close in class DXDataObject

Returns:

the same DXDataObject

closeAndWait

public DXFile closeAndWait()

Description copied from class: DXDataObject

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

Returns the same object so you can chain calls.

Overrides:

closeAndWait in class DXDataObject

Returns:

the same DXDataObject

describe

public DXFile.Describe describe()

Description copied from class: DXDataObject

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 DXDataObject.describe(DescribeOptions) instead.

Overrides:

describe in class DXDataObject

Returns:

a Describe containing the data object's metadata.

describe

public DXFile.Describe describe(DXDataObject.DescribeOptions options)

Description copied from class: DXDataObject

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

Overrides:

describe in class DXDataObject

Parameters:

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

Returns:

a Describe containing the data object's metadata.

downloadBytes

public byte[] downloadBytes()
                     throws IOException

Downloads the entire file into a byte array.

Returns:

byte array containing file contents

Throws:

IOException - if an error occurs while downloading the data

downloadBytes

public byte[] downloadBytes(long start,
                            long end)
                     throws IOException

Downloads the specified byte range of the file into a byte array. Range requested must be no larger than 2 GB.

Parameters:

start - first byte of the range within the file to be downloaded. The start byte is inclusive in the range, and 0 is indexed as the first byte in the file.

end - last byte of the range within the file to be downloaded. The end byte is exclusive (not included in the range). An input of -1 specifies the end of the file.

Returns:

byte array containing file contents within range specified

Throws:

IOException - if an error occurs while downloading the data

downloadToOutputStream

public void downloadToOutputStream(OutputStream os)
                            throws IOException

Downloads the entire file and writes the data to an OutputStream.

Parameters:

os - output stream downloaded file contents are written into

Throws:

IOException

downloadToOutputStream

public void downloadToOutputStream(OutputStream os,
                                   long start,
                                   long end)
                            throws IOException

Downloads the specified byte range of the file into an OutputStream.

Parameters:

os - output stream downloaded file contents are written into

start - first byte of the range within the file to be downloaded. The start byte is inclusive in the range, and 0 is indexed as the first byte in the file.

end - last byte of the range within the file to be downloaded. The end byte is exclusive (not included in the range). An input of -1 specifies the end of the file.

Throws:

IOException

getCachedDescribe

public DXFile.Describe getCachedDescribe()

Description copied from class: DXDataObject

Returns metadata about the data object, like DXDataObject.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.

Overrides:

getCachedDescribe in class DXDataObject

Returns:

a Describe containing the data object's metadata

getDownloadStream

public InputStream getDownloadStream()

Returns a stream of the file's contents.

Returns:

stream containing file contents

getDownloadStream

public InputStream getDownloadStream(long start,
                                     long end)

Returns a stream of the specified byte range of the file's contents.

Parameters:

start - first byte of the range within the file to be downloaded. The start byte is inclusive in the range, and 0 is indexed as the first byte in the file.

end - last byte of the range within the file to be downloaded. The end byte is exclusive (not included in the range). An input of -1 specifies the end of the file.

Returns:

stream containing file contents within range specified

getUploadStream

public OutputStream getUploadStream()

Returns an OutputStream that uploads any data written to it

The file must be in the "open" state. This method assumes exclusive access to the file: the file must have no parts uploaded before this call is made, and no other clients may upload data to the same file concurrently.

Returns:

OutputStream to which file contents are written

upload

public void upload(byte[] data)
            throws IOException

Uploads data from the specified byte array to the file.

The file must be in the "open" state. This method assumes exclusive access to the file: the file must have no parts uploaded before this call is made, and no other clients may upload data to the same file concurrently.

Parameters:

data - data in bytes to be uploaded

Throws:

IOException - if an error occurs while uploading the data

upload

public void upload(InputStream data)
            throws IOException

Uploads data from the specified stream to the file.

The file must be in the "open" state. This method assumes exclusive access to the file: the file must have no parts uploaded before this call is made, and no other clients may upload data to the same file concurrently.

Parameters:

data - stream containing data to be uploaded

Throws:

IOException - if an error occurs while uploading the data