Skip to content

Latest commit

 

History

History
384 lines (299 loc) · 8.22 KB

file-object.md

File metadata and controls

384 lines (299 loc) · 8.22 KB

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

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
);

checksum

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" );

chmod

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

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
);

create

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

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 );

exists

Validate if a file exists.

/**
* @path The file path to verify
*/
boolean function exists();

extension

Extract the extension from the file path.

string function extension();

get

Get the contents of a file.

/**
* @return The contents of the file
*
* @throws cbfs.FileNotFoundException
*/
any function get();

info

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();

isExecutable

Returns true if the file is executable.

/**
* @throws cbfs.FileNotFoundException - If the filepath is missing
* 
* @return Boolean
*/
boolean function isExecutable();

isHidden

Returns true if the file is hidden.

/**
* @throws cbfs.FileNotFoundException - If the filepath is missing
* 
* @return Boolean
*/
boolean function isHidden();

isReadable

Returns true if the file is readable.

/**
* @return Boolean
*/
boolean function isReadable();

isSymbolicLink

Returns true if the file is a symbolic link. 

/**
 * @throws cbfs.FileNotFoundException - If the filepath is missing
 * @return Boolean
 */
boolean function isSymbolicLink();

isWritable

Returns true if the file is writable.

/**
* @return Boolean
*/
boolean function isWritable();

lastModified

Retrieve the file's last modified timestamp.

/**
* @throws cbfs.FileNotFoundException
*/
function lastModified();

mimeType

Retrieve the file's mime type.

/**
 * Retrieve the file's mimetype
 * @return String
 * @throws cbfs.FileNotFoundException
 */
function mimeType();

move

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

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
);

setVisibility

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 );

size

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();

stream

{% hint style="info" %} This is currently only available when working with a Local Provider disk. {% endhint %}

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 );
};

temporaryURL

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 );

touch

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 );

url

Gets the URL of a file.

/**
 * @throws cbfs.FileNotFoundException
 */
string function url();

visibility

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();