ballerina/file1.2.2
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: false4});
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 {23 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 |
| 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. |