cbfs
  • Introduction
  • Intro
    • Release History
    • About This Book
  • Getting Started
    • Installation
    • Providers
      • Local Provider
      • RAM Provider
      • S3 Provider
  • Usage
    • Disk Service
    • Disk Usage
      • Configuration Methods
      • File Methods
      • File Object
      • Directory Methods
      • Utility Methods
      • Stream Methods
      • Verification Methods
  • Digging Deeper
    • Interceptors
    • Module Disks
    • Custom Providers
Powered by GitBook
On this page
  • append
  • checksum
  • chmod
  • copy
  • create
  • delete
  • exists
  • extension
  • get
  • info
  • isExecutable
  • isHidden
  • isReadable
  • isSymbolicLink
  • isWritable
  • lastModified
  • mimeType
  • move
  • prepend
  • setVisibility
  • size
  • stream
  • temporaryURL
  • touch
  • url
  • visibility

Was this helpful?

Edit on GitHub
Export as PDF
  1. Usage
  2. Disk Usage

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

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

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();
PreviousFile MethodsNextDirectory Methods

Last updated 2 years ago

Was this helpful?