file package

The file package provides a bridge to perform file I/O related tasks by exposing the channels of the files.

Following is a sample code snippet that can be used to write to a file,

file:Path filePath = file:getPath(pathValue);
io:ByteChannel channel = check file:newByteChannel(filePath,accessMode);
var result = channel.write(content,0);
var closeResult = channel.close();

In this code, the byteChannel of file is provided by newByteChannel function. This provides a way for ballerina/io package to continue the file write operation with the provided channel. Hence file package acts as mediation to solve the file I/O use cases.

All the CRUD(i.e. Create, Read, Update, Delete), copy and move operations involving files residing in local file systems can be accomplished using the functions exposed by this package. In-addition to that, directory listening capabilities are provided out-of-box to facilitate the additional tasks that need to be done in the event of create/update/delete of a file within the respective directory.

Path is a unique identifier of a file. Path can be either absolute or relative. Absolute path refers to complete path information of a file where the information indicates the location of a file from the root of the file system. Relative path indicates the location of a file relative to the current location of the execution. All the functions in this package expects, file:Path type as a input parameter. Retrieving file:Path of a file is simplified by getPath function.

Validations play vital role to achieve a smooth flow of a program. isDirectory, isExists are some of the functions which are mainly focused towards pre-validation. In addition to that some other utility functions are supported out-of box.

File and Directories are protected entities. Depending on the OS, CRUD operations of a file could be restricted in various ways. Depending on the restrictions imposed, some functions in this package may fail and will return AccessDenied error. In-order to reduce the functions returning errors due to access restrictions, isReadable, isWritable functions can be used to check restrictions, prior to performing any operations. Depending on the file state, functions may return errors in some other scenarios as well. One such scenario is trying to read a non-existing file.

public struct AccessDeniedError

Represents an error which occurs when attempting to perform operations on a file without the required privileges.

Field Name Data Type Description Default Value
message string The error message
cause error[] The error which caused the access denied error []
  • <AccessDeniedError> AccessDeniedError.<init>()

public struct File

Represents a file in the file system and can perform various file operations on this.

Field Name Data Type Description Default Value
path string The path of the file
  • <File> close()

    Closes a given file and its stream

  • <File> createNewFile() returns (boolean | error)

    Creates a new file given by the path in the File struct

    Return Variable Data Type Description
    boolean | error Returns true if the new file was successfully created
  • <File> delete()

    Deletes a file from a given location

  • <File> exists() returns (boolean)

    Checks whether the file exists

    Return Variable Data Type Description
    boolean Returns true if the file exists
  • <File> getModifiedTime() returns (timeTime | error)

    Returns the last modified time of the file

    Return Variable Data Type Description
    timeTime | error Returns a Time struct
  • <File> getName() returns (string)

    Returns the name of the file

    Return Variable Data Type Description
    string Returns the file name as a string
  • <File> isDirectory() returns (boolean)

    Checks whether the file is a directory

    Return Variable Data Type Description
    boolean Returns true if the file is a directory
  • <File> isReadable() returns (boolean)

    Checks whether the user has read access to the file

    Return Variable Data Type Description
    boolean Returns true if the user has read access
  • <File> isWritable() returns (boolean)

    Checks whether the user has write access to the file

    Return Variable Data Type Description
    boolean Returns true if the user has write access
  • <File> list() returns (File[] | error)

    Lists the files in the specified directory

    Return Variable Data Type Description
    File[] | error Returns an array of File structs if successful
  • <File> mkdirs() returns (boolean | error)

    Creates the directory structure specified by the file struct

    Return Variable Data Type Description
    boolean | error Returns true if the directory/directories were successfully created
  • <File> open(string accessMode)

    Retrieves the stream from a local file

    Parameter Name Data Type Description
    accessMode string The file access mode used when opening the file
  • <File> openChannel(string accessMode) returns (ByteChannel)

    Function to return a ByteChannel related to the file. This ByteChannel can then be used to read/write from/to the file.

    Parameter Name Data Type Description
    accessMode string Specifies whether the file should be opened for reading or writing (r/w)

    Return Variable Data Type Description
    ByteChannel ByteChannel which will allow to perform I/O operations
  • <File> File.<init>()

public struct FileNotFoundError

Represents an error which occurs when attempting to perform operations on a non-existent file.

Field Name Data Type Description Default Value
message string The error message
cause error[] The error which caused the file not found error []
  • <FileNotFoundError> FileNotFoundError.<init>()

public struct FileNotOpenedError

Represents an error which occurs when attempting to perform operations on a file without opening it.

Field Name Data Type Description Default Value
message string The error message
cause error[] The error which caused the file not opened error []
  • <FileNotOpenedError> FileNotOpenedError.<init>()

public struct IOError

Represents an I/O error which could occur when processing a file.

Field Name Data Type Description Default Value
message string The error message
cause error[] The error which caused the I/O error []
  • <IOError> IOError.<init>()

public function copy(File source, File destination)

Copies a file from a given location to another

Parameter Name Data Type Description
source File File/Directory that should be copied
destination File Destination directory or path to which the source should be copied

public function move(File target, File destination)

Moves a file from a given location to another

Parameter Name Data Type Description
target File File/Directory that should be moved
destination File Location where the File/Directory should be moved to

R

Attribute Name Data Type Description
R string The Read access mode

W

Attribute Name Data Type Description
W string The Write access mode

RW

Attribute Name Data Type Description
RW string The Read Write access mode

A

Attribute Name Data Type Description
A string The Append access mode

RA

Attribute Name Data Type Description
RA string The Read Append access mode