ballerina/file

Overview

This module provides APIs, which perform file, file path, and directory operations, and a Directory Listener, which is used to listen to a directory in the local file system.

This provides the interface to create, delete, rename the file/directory, retrieve metadata of the given file, and manipulate the filename paths in a way that is compatible according to the target file paths defined by the operating system.

The path of the file/directory needs to be defined with either forward slashes or back slashes depending on the operating system.

Directory Listener

The file:Listener is used to monitor all the files and subdirectories inside the specified directory.

A Listener endpoint can be defined using the mandatory path parameter and the optional recursive parameter as follows.

1listener file:Listener inFolder = new ({
2 path: "<The directory path>",
3 recursive: false
4});

If the listener needs to monitor subdirectories of the given directory, recursive needs to be set to true. The default value of this is false.

A Service has the defined remote methods with the file:FileEvent and can be exposed via a Listener endpoint. When there are changes in the listening directory, the file:FileEvent will be triggered with the action of the file such as creating, modifying, or deleting.

The remote methods supported by the Service are as follows.

onCreate: This method is invoked once a new file is created in the listening directory.

onDelete: This method is invoked once an existing file is deleted from the listening directory.

onDelete: This method is invoked once an existing file is modified in the listening directory.

The following code sample shows how to create a Service with the onCreate remote method and attach it to the above Listener endpoint:

1service "localObserver" on inFolder {
2
3 remote function onCreate(file:FileEvent m) {
4 string msg = "Create: " + m.name;
5 log:printInfo(msg);
6 }
7}

For information on the operations, which you can perform with the regex module, see the below Functions.

Listeners

[1]

Listener

Represents the directory listener endpoint, which is used to listen to a directory in the local file system.

Functions

[19]

basename

Retrieves the base name of the file from the provided location, which is the last element of the path.

copy

Copy the file/directory in the old path to the new path.

create

Creates a file in the specified file path.

createDir

Creates a new directory with the specified name.

createTemp

Creates a temporary file.

createTempDir

Creates a temporary directory.

getAbsolutePath

Retrieves the absolute path from the provided location.

getCurrentDir

Returns the current working directory.

getMetaData

Returns the metadata information of the file specified in the file path.

isAbsolutePath

Reports whether the path is absolute.

joinPath

Joins any number of path elements into a single path.

normalizePath

Normalizes a path value.

parentPath

Returns the enclosing parent directory.

readDir

Reads the directory and returns a list of metadata of files and directories inside the specified directory.

relativePath

Returns a relative path, which is logically equivalent to the target path when joined to the base path with an intervening separator.

remove

Removes the specified file or directory.

rename

Renames(Moves) the old path with the new path.

splitPath

Splits a list of paths joined by the OS-specific path separator.

test

Tests a file path against a test condition .

Records

[3]

FileEvent

Represents an event which will trigger when there is a changes to listining direcotry.

ListenerConfig

Represents configurations that required for directory listener.

MetaData

Metadata record contains metadata information of a file.

Enums

[4]

CopyOption

Represents options that can be used when copying files/directories

DirOption

Represents options that can be used when creating or removing directories.

NormOption

Represents the options that can be passed to normalizePath function.

TestOption

Represents the options that can be passed to test function.

Errors

[13]

Error

Represents file system related errors.

FileNotFoundError

Represents an error that occurs when the file/directory does not exist at the given filepath.

FileSystemError

Represents an error that occurs when a file system operation fails.

GenericError

Represents generic error for filepath.

InvalidOperationError

Represents an error that occurs when a file system operation is denied due to invalidity.

InvalidPathError

Represents error occur when the given file path is invalid.

InvalidPatternError

Represent error occur when the given pattern is not a valid filepath pattern.

IOError

Represents IO error occur when trying to access the file at the given filepath.

NotLinkError

Represents error occur when the file at the given filepath is not a symbolic link.

PermissionError

Represents an error that occurs when a file system operation is denied, due to the absence of file permission.

RelativePathError

Represents an error that occurs when the given target filepath cannot be derived relative to the base filepath.

SecurityError

Represents security error occur when trying to access the file at the given filepath.

UNCPathError

Represents error occur in the UNC path.