org.mule.extension.file.common.api

Interface FileSystem

All Known Implementing Classes:

AbstractFileSystem

public interface FileSystem

Represents an abstract file system and the operations which can be performed on it.

This interface acts as a facade which allows performing common files operations regardless of those files being in a local disk, an FTP server, a cloud storage service, etc.

Since:

1.0

Method Summary

Modifier and Type	Method and Description
void	changeToBaseDir() Changes the current working directory to the user base
void	copy(FileConnectorConfig config, String sourcePath, String targetPath, boolean overwrite, boolean createParentDirectories, String renameTo) Copies the file at the sourcePath into the targetPath.
void	createDirectory(String directoryPath) Creates a new directory
Lock	createMuleLock(String id)
void	delete(String filePath) Deletes the file pointed by filePath, provided that it's not locked
Class<? extends FileAttributes>	getAttributesType() The concrete class that represents the attributes related to the FileSystem implementation.
String	getBasePath()
org.mule.runtime.api.metadata.MediaType	getFileMessageMediaType(org.mule.runtime.api.metadata.MediaType originalMediaType, FileAttributes attributes) Creates a new DataType to be associated with a Message which payload is a InputStream and the attributes an instance of FileAttributes
List<org.mule.runtime.extension.api.runtime.operation.Result<InputStream,FileAttributes>>	list(FileConnectorConfig config, String directoryPath, boolean recursive, org.mule.runtime.api.metadata.MediaType mediaType, Predicate<FileAttributes> matcher) Lists all the files in the directoryPath which match the given matcher.
PathLock	lock(Path path, Object... params) Acquires and returns lock over the given path.
void	move(FileConnectorConfig config, String sourcePath, String targetPath, boolean overwrite, boolean createParentDirectories, String renameTo) Moves the file at the sourcePath into the targetPath.
org.mule.runtime.extension.api.runtime.operation.Result<InputStream,FileAttributes>	read(FileConnectorConfig config, String filePath, org.mule.runtime.api.metadata.MediaType mediaType, boolean lock) Obtains the content and metadata of a file at a given path.
void	rename(String filePath, String newName, boolean overwrite) Renames the file pointed by filePath to the provided newName
void	verifyNotLocked(Path path) Verify that the given path is not locked
void	write(String filePath, InputStream content, FileWriteMode mode, boolean lock, boolean createParentDirectories, String encoding) Writes the content into the file pointed by filePath.

Method Detail

list

List<org.mule.runtime.extension.api.runtime.operation.Result<InputStream,FileAttributes>> list(FileConnectorConfig config,
                                                                                               String directoryPath,
                                                                                               boolean recursive,
                                                                                               org.mule.runtime.api.metadata.MediaType mediaType,
                                                                                               Predicate<FileAttributes> matcher)

Lists all the files in the directoryPath which match the given matcher.

If the listing encounters a directory, the output list will include its contents depending on the value of the recursive argument. If recursive is enabled, then all the files in that directory will be listed immediately after their parent directory.

If recursive is set to true but a found directory is rejected by the matcher, then there won't be any recursion into such directory.

Parameters:

config - the config that is parameterizing this operation

directoryPath - the path to the directory to be listed

recursive - whether to include the contents of sub-directories

matcher - a Predicate of FileAttributes used to filter the output list

mediaType - the MediaType of the message which entered the operation

Returns:

a List of Result objects, each one containing each file's content in the payload and metadata in the attributes

Throws:

IllegalArgumentException - if directoryPath points to a file which doesn't exists or is not a directory

read

org.mule.runtime.extension.api.runtime.operation.Result<InputStream,FileAttributes> read(FileConnectorConfig config,
                                                                                         String filePath,
                                                                                         org.mule.runtime.api.metadata.MediaType mediaType,
                                                                                         boolean lock)

Obtains the content and metadata of a file at a given path.

Locking can be actually enabled through the lock argument, however, the extent of such lock will depend on the implementation. What is guaranteed by passing true on the lock argument is that this instance will not attempt to modify this file until the InputStream returned by Result.getOutput() this method returns is closed or fully consumed. Some implementation might actually perform a file system level locking which goes beyond the extend of this instance or even mule. For some other file systems that might be simply not possible and no extra assumptions are to be taken.

This method also makes a best effort to determine the mime type of the file being read. a MimetypesFileTypeMap will be used to make an educated guess on the file's mime type

Parameters:

config - the config that is parameterizing this operation

filePath - the path of the file you want to read

mediaType - The MediaType of the message that on which this operations is being executed

lock - whether or not to lock the file

Returns:

An Result with an InputStream with the file's content as payload and a FileAttributes object as Message.getAttributes()

Throws:

IllegalArgumentException - if the file at the given path doesn't exists

write

void write(String filePath,
           InputStream content,
           FileWriteMode mode,
           boolean lock,
           boolean createParentDirectories,
           String encoding)

Writes the content into the file pointed by filePath.

The content can be of any of the given types:

• String
• String[]
• byte
• byte[]
• OutputHandler
• Iterable
• Iterator

null contents are not allowed and will result in an IllegalArgumentException.

If the directory on which the file is attempting to be written doesn't exist, then the operation will either throw IllegalArgumentException or create such folder depending on the value of the createParentDirectory.

If the file itself already exists, then the behavior depends on the supplied mode.

This method also supports locking support depending on the value of the lock argument, but following the same rules and considerations as described in the read(FileConnectorConfig, String, MediaType, boolean) method

Parameters:

filePath - the path of the file to be written

content - the content to be written into the file

mode - a FileWriteMode

lock - whether or not to lock the file

createParentDirectories - whether or not to attempt creating any parent directories which don't exists.

encoding - when is a String, this attribute specifies the encoding to be used when writing. If not set, then it defaults to FileConnectorConfig.getDefaultWriteEncoding()

Throws:

IllegalArgumentException - if an illegal combination of arguments is supplied

copy

void copy(FileConnectorConfig config,
          String sourcePath,
          String targetPath,
          boolean overwrite,
          boolean createParentDirectories,
          String renameTo)

Copies the file at the sourcePath into the targetPath.

If targetPath doesn't exists, and neither does its parent, then an attempt will be made to create depending on the value of the createParentDirectory argument. If such argument is , then an IllegalArgumentException will be thrown.

It is also possible to use the targetPath to specify that the copied file should also be renamed. For example, if sourcePath has the value a/b/test.txt and targetPath is assigned to a/c/test.json, then the file will indeed be copied to the a/c/ directory but renamed as test.json

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException will be thrown

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be copied recursively

Parameters:

config - the config that is parameterizing this operation

sourcePath - the path to the file to be copied

targetPath - the target directory

overwrite - whether or not overwrite the file if the target destination already exists.

createParentDirectories - whether or not to attempt creating any parent directories which don't exists.

renameTo - the new file name, null if the file doesn't need to be renamed

Throws:

IllegalArgumentException - if an illegal combination of arguments is supplied

move

void move(FileConnectorConfig config,
          String sourcePath,
          String targetPath,
          boolean overwrite,
          boolean createParentDirectories,
          String renameTo)

Moves the file at the sourcePath into the targetPath.

If targetPath doesn't exists, and neither does its parent, then an attempt will be made to create depending on the value of the createParentDirectory argument. If such argument is , then an IllegalArgumentException will be thrown.

It is also possible to use the targetPath to specify that the moved file should also be renamed. For example, if sourcePath has the value a/b/test.txt and targetPath is assigned to a/c/test.json, then the file will indeed be moved to the a/c/ directory but renamed as test.json

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException will be thrown

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be moved recursively

Parameters:

config - the config that is parameterizing this operation

sourcePath - the path to the file to be copied

targetPath - the target directory

overwrite - whether or not overwrite the file if the target destination already exists.

createParentDirectories - whether or not to attempt creating any parent directories which don't exists.

renameTo - the new file name, null if the file doesn't need to be renamed

Throws:

IllegalArgumentException - if an illegal combination of arguments is supplied

delete

void delete(String filePath)

Deletes the file pointed by filePath, provided that it's not locked

Parameters:

filePath - the path to the file to be deleted

Throws:

IllegalArgumentException - if filePath doesn't exists or is locked

rename

void rename(String filePath,
            String newName,
            boolean overwrite)

Renames the file pointed by filePath to the provided newName

Parameters:

filePath - the path to the file to be renamed

newName - the file's new name

overwrite - whether or not overwrite the file if the target destination already exists.

createDirectory

void createDirectory(String directoryPath)

Creates a new directory

Parameters:

directoryPath - the new directory's path

lock

PathLock lock(Path path,
              Object... params)

Acquires and returns lock over the given path.

Depending on the underlying filesystem, the extent of the lock will depend on the implementation. If a lock can not be acquired, then an IllegalStateException is thrown.

Whoever request the lock MUST release it as soon as possible.

Parameters:

path - the path to the file you want to lock

params - vararg of generic arguments depending on the underlying implementation

Returns:

an acquired PathLock

Throws:

IllegalArgumentException - if a lock could not be acquired

createMuleLock

Lock createMuleLock(String id)

getFileMessageMediaType

org.mule.runtime.api.metadata.MediaType getFileMessageMediaType(org.mule.runtime.api.metadata.MediaType originalMediaType,
                                                                FileAttributes attributes)

Creates a new DataType to be associated with a Message which payload is a InputStream and the attributes an instance of FileAttributes

It will try to update the DataType.getMediaType() with a best guess derived from the given attributes. If no best-guess is possible, then the originalDataType's mimeType is honoured.

As for the MediaType.getCharset(), the dataType one is respected

Parameters:

originalMediaType - the original MediaType that the Message had before executing the operation

attributes - the FileAttributes of the file being processed

Returns:

a DataType the resulting DataType.

verifyNotLocked

void verifyNotLocked(Path path)

Verify that the given path is not locked

Parameters:

path - the path to test

Throws:

IllegalStateException - if the path is indeed locked

changeToBaseDir

void changeToBaseDir()

Changes the current working directory to the user base

getAttributesType

Class<? extends FileAttributes> getAttributesType()

The concrete class that represents the attributes related to the FileSystem implementation.

This method is called when handling the dynamic resolution for the output attributes metadata of an operation.

getBasePath

String getBasePath()