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 |