ballerina/file

Overview

This module provides APIs to create, delete, rename the file/directory, retrieve metadata of the given file, and manipulate the file paths in a way that is compatible with the operating system, and a Directory Listener, which is used to listen to the file changes in a directory in the local file 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.

onModify: 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 file 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 .

Object types

[1]

Service

Represents a File service.

Records

[3]

FileEvent

Represents an event, which will trigger when there is a change to the listening directory.

ListenerConfig

Represents the configurations that are required for a 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 the normalizePath function.

TestOption

Represents the options that can be passed to the test function.

Errors

[13]

Error

Represents file system related errors.

FileNotFoundError

Represents an error, which occurs when the file/directory does not exist in the given file path.

FileSystemError

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

GenericError

Represents a generic error for the file path.

InvalidOperationError

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

InvalidPathError

Represents an error, which occurs when the given file path is invalid.

InvalidPatternError

Represents an error, which occurs when the given pattern is not a valid file path pattern.

IOError

Represents an IO error, which occurs when trying to access the file in the given file path.

NotLinkError

Represents an error, which occurs when the file in the given file path 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, which occurs when the given target file path cannot be derived relative to the base file path.

SecurityError

Represents a security error, which occurs when trying to access the file in the given file path.

UNCPathError

Represents an error, which occurs in the UNC path.