Class: File

binding.File(fileOptions)

Creates a file object, which represents one specific file reference.
This File object can afterwards be used to up- and download the file contents or to retrieves and change the files
metadata.

The file data can be uploaded and downloaded as:




































type JavaScript type Description
'arraybuffer' ArrayBuffer The content is represented as a fixed-length raw binary data buffer
'blob'
Blob The content is represented as a simple blob
'json' object|array|string The file content is represented as json
'text' string The file content is represented through the string
'base64' string The file content as base64 encoded string
'data-url' string A data url which represents the file content

Constructor

new File(fileOptions)

Creates a new file object which represents a file at the given id. Data which is provided to the constructor will
be uploaded by invoking upload()

Parameters:
Name Type Description
fileOptions object | string

The fileOptions used to create a new file object, or just the id of the file

Properties
Name Type Attributes Default Description
id string <optional>

The id of the file.

name string <optional>

The filename without the id. If omitted and data is provided as a file object,
the File#name will be used otherwise a UUID will be generated.

parent string <optional>
"/www"

The parent folder which contains the file

path string <optional>
"/www"

The full path of the file.
You might either specify the path of the file or a combination of parent and file name.

data string | Blob | File | ArrayBuffer | json

The initial file content, which will be uploaded by
invoking #upload later on.

type string <optional>

A optional type hint used to correctly interpret the provided data

mimeType string <optional>

The mimType of the file. Defaults to the mimeType of the provided data if
it is a file object, blob or data-url

size number <optional>

The size of the file content in bytes

eTag string <optional>

The optional current ETag of the file

lastModified string | Date

The optional last modified date

acl Acl <optional>

The file acl which will be set, if the file is uploaded afterwards

headers Object.<string, string> <optional>

The custom headers which will be send with the file after
uploading it

Source:

Members

(readonly) acl :Acl

The current file acl, only accessible after fetching the metadata or downloading/uploading/providing the file

Type:
Source:

(readonly) bucket :string

Type:
  • string
Source:

(readonly, nullable) createdAt :Date

The creation date of the file, only accessible after fetching the metadata
or downloading/uploading/providing the eTag

Type:
  • Date
Source:

(readonly) eTag :string

The eTag of the file, only accessible after fetching the metadata or downloading/uploading/providing the file

Type:
  • string
Source:

(readonly) headers :Object.<string, string>

The custom headers of the file, only accessible after fetching the metadata or downloading/uploading/providing
the file

Type:
  • Object.<string, string>
Source:

(readonly) id :string

The complete id of the file, including folder and name

Type:
  • string
Source:

(readonly) isFolder :boolean

Specifies whether this file is a folder.

Type:
  • boolean
Source:

(readonly) isMetadataLoaded :boolean

Indicates if the metadata are loaded.

Type:
  • boolean
Source:

(readonly) key :string

Type:
  • string
Source:

(readonly, nullable) lastModified :Date

The last modified date of the file, only accessible after fetching the metadata
or downloading/uploading/providing the eTag

Type:
  • Date
Source:

(readonly) mimeType :string

The mimeType of the file, only accessible after fetching the metadata or downloading/uploading/providing the file

Type:
  • string
Source:

(readonly) name :string

The name of the file

Type:
  • string
Source:

(readonly) parent :string

The parent folder of the file.

Type:
  • string
Source:

(readonly) path :string

The full path of the file.

Type:
  • string
Source:

(readonly) size :number

The size of the file, only accessible after fetching the metadata or downloading/uploading/providing the file

Type:
  • number
Source:

(readonly) url :string

The fully url to the file, can be directly used to link the file, i.e. in link tags ot image sources

Type:
  • string
Source:

Methods

(static) parseETag(eTagopt) → (nullable) {string}

Parses an E-Tag header

Parameters:
Name Type Attributes Description
eTag string <optional>

The E-Tag to parse or something falsy

Source:
Returns:

Returns the parsed E-Tag or null, if it could not be parsed

Type
string

checkAvailable() → {void}

Checks whenever metadata are already loaded of the file, throws an error otherwise

Source:
Returns:
Type
void

conditional(msg, options) → {void}

Makes the given message a conditional request based on the file metadata

Parameters:
Name Type Description
msg connector.Message

The message to make conditional

options object

additional request options

Properties
Name Type Attributes Default Description
force boolean <optional>
false

Force the request operation by didn't make it conditional

Source:
Returns:
Type
void

delete(deleteOptionsopt, doneCallbackopt, failCallbackopt) → {Promise.<(binding.File|Array.<binding.File>)>}

Deletes a file

Parameters:
Name Type Attributes Description
deleteOptions object <optional>

The delete options

Properties
Name Type Attributes Default Description
force boolean <optional>
false

force the deletion without verifying any version

doneCallback binding.File~deleteCallback <optional>

The callback is invoked after the deletion succeed successfully

failCallback binding.File~failCallback <optional>

The callback is invoked if any error is occurred

Source:
Returns:

A promise which will be fulfilled with this file object,
or with a list of all deleted files, if this file is an folder

Type
Promise.<(binding.File|Array.<binding.File>)>

download(downloadOptionsopt, doneCallbackopt, failCallbackopt) → {Promise.<(string|Blob|File|ArrayBuffer|json)>}

Download a file and providing it in the requested type

Parameters:
Name Type Attributes Description
downloadOptions object <optional>

The download options

Properties
Name Type Attributes Default Description
type string <optional>
"blob"

The type used to provide the file

refresh string <optional>
false

Indicates to make a revalidation request and not use the cache

doneCallback binding.File~downloadCallback <optional>

The callback is invoked after the download succeed
successfully

failCallback binding.File~failCallback <optional>

The callback is invoked if any error is occurred

Source:
Returns:

A promise which will be fulfilled with the downloaded
file content

Type
Promise.<(string|Blob|File|ArrayBuffer|json)>

fromJSON(json) → {void}

Deserialize the given JSON file metadata back to this file instance

If the JSON object contains an ID, it must match with this file ID, otherwise an exception is thrown.

Parameters:
Name Type Description
json json

The json to deserialize

Source:
Returns:
Type
void

loadMetadata(optionsopt, doneCallbackopt, failCallbackopt) → {Promise.<binding.File>}

Gets the file metadata of a file

Parameters:
Name Type Attributes Description
options Object <optional>

The load metadata options

Properties
Name Type Attributes Default Description
refresh Object <optional>
false

Force a revalidation while fetching the metadata

doneCallback binding.File~fileCallback <optional>

The callback is invoked after the metadata is fetched

failCallback binding.File~failCallback <optional>

The callback is invoked if any error has occurred

Source:
Returns:

A promise which will be fulfilled with this file

Type
Promise.<binding.File>

saveMetadata(optionsopt, doneCallbackopt, failCallbackopt) → {Promise.<binding.File>}

Updates the matadata of this file.

Parameters:
Name Type Attributes Description
options Object <optional>

The save metadata options

Properties
Name Type Attributes Default Description
force boolean <optional>
false

force the update and overwrite the existing metadata without validating it

doneCallback binding.File~fileCallback <optional>

The callback is invoked after the metadata is saved

failCallback binding.File~failCallback <optional>

The callback is invoked if any error has occurred

Source:
Returns:

A promise which will be fulfilled with this file

Type
Promise.<binding.File>

toJSON() → {json}

Serialize the file metadata of this object to json

Source:
Returns:

The serialized file metadata as json

Type
json

upload(uploadOptionsopt, doneCallbackopt, failCallbackopt) → {Promise.<binding.File>}

Uploads the file content which was provided in the constructor or by uploadOptions.data

Parameters:
Name Type Attributes Description
uploadOptions object <optional>

The upload options

Properties
Name Type Attributes Default Description
data string | Blob | File | ArrayBuffer | json <optional>

The initial file content, which will be uploaded by
invoking #upload later on.

type string <optional>

A optional type hint used to correctly interpret the provided data

mimeType string <optional>

The mimType of the file. Defaults to the mimeType of the provided data if
it is a file object, blob or data-url

eTag string <optional>

The optional current ETag of the file

lastModified string <optional>

The optional last modified date

acl Acl <optional>

The file acl which will be set, if the file is uploaded afterwards

headers Object.<string, string> <optional>

The custom headers which will be send with the file after
uploading it

force boolean <optional>
false

force the upload and overwrite any existing files without validating
it

progress connector.Message~progressCallback <optional>

listen to progress changes during upload

doneCallback binding.File~fileCallback <optional>

The callback is invoked after the upload succeed successfully

failCallback binding.File~failCallback <optional>

The callback is invoked if any error is occurred

Source:
Returns:

A promise which will be fulfilled with this file object
where the metadata is updated

Type
Promise.<binding.File>

Type Definitions

deleteCallback(data) → {*}

The delete callback is called, when the asynchronous deletion completes successfully

Parameters:
Name Type Description
data binding.File

The file metadata

Source:
Returns:

A Promise, result or undefined

Type
*

downloadCallback(data) → {*}

The download callback is called, when the asynchronous download completes successfully

Parameters:
Name Type Description
data string | Blob | File | ArrayBuffer | json

The download file content in the requested format

Source:
Returns:

A Promise, result or undefined

Type
*

failCallback(error) → {*}

The fail callback is called, when the asynchronous operation is rejected by an error

Parameters:
Name Type Description
error error.PersistentError

The error which reject the operation

Source:
Returns:

A Promise, result or undefined

Type
*

fileCallback(file) → {*}

The file callback is called, when the asynchronous operation completes successfully

Parameters:
Name Type Description
file binding.File

The updated file metadata

Source:
Returns:

A Promise, result or undefined

Type
*