File Object
The CBFS File object gives you simplied access to the disk API.
To create a new file object, you an use:
var file = disk.file( "some/path/somefile.txt" );
Then you can access any of the api methods documented here. Enjoy!
var file = disk.file( "somefile.txt" )
.create( "some contents" )
.append( "append contents" );
var mimeType = file.mimeType(); // returns 'text/plain'
Append contents to the end of a file.
/**
* @contents The contents of the file to append
* @metadata Struct of metadata to store with the file
* @throwOnMissing Boolean flag to throw if the file is missing. Otherwise it will be created if missing.
*
* @return File
*
* @throws cbfs.FileNotFoundException
*/
function append(
required contents,
struct metadata = {},
boolean throwOnMissing = false
);
Generate checksum for a file in different hashing algorithms.
/**
* Generate checksum for a file in different hashing algorithms
*
* @algorithm Default is MD5, but SHA-1, SHA-256, and SHA-512 can also be used.
*
* @throws cbfs.FileNotFoundException
*/
string function checksum( algorithm = "MD5" );
Sets the access attributes of the file on Unix based disks.
/**
* @mode Access mode, the same attributes you use for the Linux command `chmod`
* @return File
*/
function chmod( required string mode );
Copy a file from one destination to another.
/**
* @destination The end destination path
* @overwrite Flag to overwrite the file at the destination, if it exists. Defaults to true.
*
* @return File - returns the copied file object
*
* @throws cbfs.FileNotFoundException - When the source doesn't exist
* @throws cbfs.FileOverrideException - When the destination exists and no override has been provided
*/
function copy(
required destination,
boolean overwrite = true
);
Creates a file on the disk.
/**
* @contents The contents of the file to store
* @visibility The storage visibility of the file, available options are `public, private, readonly` or a custom data type the implemented driver can interpret
* @metadata Struct of metadata to store with the file
* @overwrite Flag to overwrite the file at the destination, if it exists. Defaults to true.
* @mode Applies to *nix systems. If passed, it overrides the visbility argument and uses these octal values instead
*
* @return File
*
* @throws cbfs.FileOverrideException - When a file exists and no override has been provided
*/
function create(
required contents,
string visibility,
struct metadata = {},
boolean overwrite = true,
string mode
);
Delete a file or an array of file paths. If a file does not exist a
false will be shown for its return./**
* @throwOnMissing Boolean to throw an exception if the file is missing.
*
* @return boolean
*
* @throws cbfs.FileNotFoundException
*/
boolean function delete( boolean throwOnMissing = false );
Validate if a file exists.
/**
* @path The file path to verify
*/
boolean function exists();
Extract the extension from the file path.
string function extension();
Get the contents of a file.
/**
* @return The contents of the file
*
* @throws cbfs.FileNotFoundException
*/
any function get();
Return information about the file. Will contain keys such as lastModified, size, path, name, type, canWrite, canRead, isHidden and more depending on the provider used.
/**
* @return A struct of file metadata according to provider
*
* @throws cbfs.FileNotFoundException
*/
struct function info();
Returns true if the file is executable.
/**
* @throws cbfs.FileNotFoundException - If the filepath is missing
*
* @return Boolean
*/
boolean function isExecutable();
Returns true if the file is hidden.
/**
* @throws cbfs.FileNotFoundException - If the filepath is missing
*
* @return Boolean
*/
boolean function isHidden();
Returns true if the file is readable.
/**
* @return Boolean
*/
boolean function isReadable();
Returns true if the file is a symbolic link.
/**
* @throws cbfs.FileNotFoundException - If the filepath is missing
* @return Boolean
*/
boolean function isSymbolicLink();
Returns true if the file is writable.
/**
* @return Boolean
*/
boolean function isWritable();
Retrieve the file's last modified timestamp.
/**
* @throws cbfs.FileNotFoundException
*/
function lastModified();
Retrieve the file's mime type.
/**
* Retrieve the file's mimetype
* @return String
* @throws cbfs.FileNotFoundException
*/
function mimeType();
Move a file from one destination to another.
/**
* @destination The end destination path
*
* @return File - the moved file object
*
* @throws cbfs.FileNotFoundException - When the source doesn't exist
* @throws cbfs.FileOverrideException - When the destination exists and no override has been provided
*/
function move(
required destination,
boolean overwrite = true
);
Prepend contents to the beginning of a file. This is a very expensive operation for local disk storage.
/**
* @contents The contents of the file to prepend
* @metadata Struct of metadata to store with the file
* @throwOnMissing Boolean flag to throw if the file is missing. Otherwise it will be created if missing.
*
* @return File
*
* @throws cbfs.FileNotFoundException
*/
function prepend(
required contents,
struct metadata = {},
boolean throwOnMissing = false
);
Set the storage visibility of a file. Available options are
public, private, readonly or a custom data type the implemented driver can interpret./**
* @visibility The storage visibility of the file, available options are `public, private, readonly` or a custom data type the implemented driver can interpret
*
* @return File
*/
function setVisibility( required string visibility );
Returns the size of a file (in bytes). The size may differ from the actual size on the file system due to compression, support for sparse files, or other reasons.
/**
* @throws cbfs.FileNotFoundException
*/
numeric function size();
This is currently only available when working with a Local Provider disk.
Return a Java stream of the file using non-blocking IO classes. The stream will represent every line in the file so you can navigate through it. This method leverages the
cbstreams library used accordingly by implementations (https://www.forgebox.io/view/cbstreams)/**
* @return Stream object: See https://apidocs.ortussolutions.com/coldbox-modules/cbstreams/1.1.0/index.html
*/
function stream(){
arguments.path = getPath();
return getDisk().stream( argumentCollection=arguments );
};
Get a temporary URL for the given file.
/**
* @expiration The number of minutes this url should be valid for. Defaults to 60 minutes
*/
string function temporaryUrl( numeric expiration = 60 );
Create a new empty file if it does not exist.
/**
* @createPath if set to false, expects all parent directories to exist, true will generate necessary directories. Defaults to true.
*
* @return File
*
* @throws cbfs.PathNotFoundException
*/
function touch( boolean createPath = true );
Gets the URL of a file.
/**
* @throws cbfs.FileNotFoundException
*/
string function url();
Get the storage visibility of a file. The return format can be a string of
public, private, readonly or a custom data type the implemented driver can interpret./**
* @return String
*/
string function visibility();
Last modified 5mo ago