Package de.xima.fc.interfaces.workflow.execution

Interface IWorkflowFileHandler

public interface IWorkflowFileHandler

Handler with utility methods for working with files during the execution of a workflow, and making these files available to other workflow node. Contains methods such as attaching files to the form record or saving files to the file system.

Useful for node action that implement IProviding and IAttachableFile.

Since:

7.0.0

Author:

XIMA MEDIA GmbH

Method Summary

Modifier and Type	Method	Description
default List<Attachment>	attachFilesToFormRecord(File... files)	Attaches the given files to the current form record for which the workflow is executed.
List<Attachment>	attachFilesToFormRecord(Iterable<File> files)	Attaches the given files to the current form record for which the workflow is executed.
default List<File>	copyFilesToDir(File[] sourceFileOrDirectories, File targetDir)	Deprecated. Use copyFilesToDir(File[], File, EFileConflictMode).
default List<File>	copyFilesToDir(File[] sourceFileOrDirectories, File targetDir, EFileConflictMode mode)	Copies the source files to the given target directory.
default File	copyFilesToDir(File sourceFileOrDirectory, File targetDir)	Deprecated. Use copyFilesToDir(File, File, EFileConflictMode).
File	copyFilesToDir(File sourceFileOrDirectory, File targetDir, EFileConflictMode mode)	Copies the source files to the given target directory.
default List<File>	copyFilesToDir(Iterable<File> sourceFileOrDirectories, File targetDir)	Deprecated. Use copyFilesToDir(Iterable, File, EFileConflictMode).
default List<File>	copyFilesToDir(Iterable<File> sourceFileOrDirectories, File targetDir, EFileConflictMode mode)	Copies the source files to the given target directory.
File	copyFileTo(File sourceFile, File targetFile, EFileConflictMode mode)	Copies the given file to the target directory and file name.
List<Attachment>	getAttachmentsFromUploadElements(List<String> uploadElements, Vorgang formRecord, IFormDataAdapter formDataAdapter)	Determines the upload attachments from the specified form record.
List<List<File>>	getFilesFromPreviousNode(WorkflowNode previousNode)	Returns all files from given node.
default List<File>	getFilesFromPreviousNodes(WorkflowNode... previousNodes)	Returns all files from the given previous nodes.
List<File>	getFilesFromPreviousNodes(Iterable<WorkflowNode> previousNode)	Returns all files from given nodes.
default List<IResolvedFile>	getFilesFromUploadElements(IUploadConsuming consuming)	Same as getFilesFromUploadElements(List), but takes the parameters from the given IUploadConsuming corresponding.
List<IResolvedFile>	getFilesFromUploadElements(List<String> uploadElements)	Returns a list of all files from the given upload elements.
IResolvedFile	getFileSingle(WorkflowNode node, ISingleFileProviding singleFile, IFileSearchOptions options)	Returns the file represented by the given descriptor.
IResolvedMultiFile	getFilesMulti(WorkflowNode node, IMultiFileProviding multiFile, IFileSearchOptions options)	Returns the files represented by the given descriptor.
IGuessedContentType	guessContentType(File file)
IGuessedContentType	guessContentType(String fileName, byte[] contents)
default List<File>	listFiles(File[] directories, boolean recursive, Iterable<String> extensions)	Lists all files contained in the given directories.
default List<File>	listFiles(File[] directories, boolean recursive, String... extensions)	Lists all files contained in the given directories.
default List<File>	listFiles(File directory, boolean recursive, Iterable<String> extensions)	Lists all files contained in the given directory.
List<File>	listFiles(File directory, boolean recursive, String... extensions)	Lists all files contained in the given directory.
default List<File>	listFiles(Iterable<File> directories, boolean recursive, Iterable<String> extensions)	Lists all files contained in the given directories.
List<File>	listFiles(Iterable<File> directories, boolean recursive, String... extensions)	Lists all files contained in the given directories.
default File	randomSourceDirForNode(WorkflowNode node, String... subDirs)	Creates a random temporary directory inside the given source directory of the node.
default File	randomTargetDirForNode(WorkflowNode node, String... subDirs)	Creates a random temporary directory inside the given target directory of the node.
File	randomTempDirForNode(WorkflowNode node, String... subDirs)	Creates a random temporary directory inside the given sub directory for the node.
default String	sanitizeFilename(String fileName)
String	sanitizeFilename(String fileName, IPlaceholderEscaper placeholderEscaper)
default File	sourceDirForNode(WorkflowNode node, String... subDirs)	Shortcut for getTempDirForNode(node, "source").
default File	sourceFileForNode(WorkflowNode node, String... subDirs)	Shortcut for getTempFileForNode(node, "source").
default File	subDirectory(File baseDir, Iterable<String> subDirs)	Starting at the given base directory, accesses the given sub directories, creates that sub directory if necessary, and returns a file corresponding to that sub directory.
File	subDirectory(File baseDir, String... subDirs)	Starting at the given base directory, accesses the given sub directories, creates that sub directory if necessary, and returns a file corresponding to that sub directory.
default File	subFile(File baseDir, Iterable<String> subDirs)	Similar to subDirectory(File, String...), but with the different that this method does not create a directory for the last item in the given subDirs.
File	subFile(File baseDir, String... subDirs)	Similar to subDirectory(File, String...), but with the different that this method does not create a directory for the last item in the given subDirs.
default File	targetDirForNode(WorkflowNode node, String... subDirs)	Shortcut for getTempDirForNode(node, "target").
default File	targetFileForNode(WorkflowNode node, String... subDirs)	Shortcut for getTempFileForNode(node, "target").
File	tempDirForNode(WorkflowNode node, String... subDirs)	Path to the temporary target directory for the given workflow node.
File	tempDirShared(String... subDirs)	Return a path to the temporary directory shared by all workflow nodes.
File	tempFileForNode(WorkflowNode node, String... subDirs)	Returns the path to a file in the temporary target directory for the given workflow node.
File	tempFileShared(String... subDirs)	Return a file within to the temporary directory shared by all workflow nodes.
File	withExtension(File file, String newExtension)	Changes the extension of the file name to the given extension.
String	withExtension(String fileName, String newExtension)	Changes the extension of the file name to the given extension.
default File	writeToSourceDir(WorkflowNode node, byte[] data, String... path)	Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToSourceDir(WorkflowNode node, IFileProviding<?,? extends IFileDataEntity<?>> providing, String... subDirs)	Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToSourceDir(WorkflowNode node, File data, String... path)	Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToSourceDir(WorkflowNode node, InputStream data, String... path)	Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTargetDir(WorkflowNode node, byte[] data, String... path)	Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTargetDir(WorkflowNode node, IFileProviding<?,? extends IFileDataEntity<?>> providing, String... subDirs)	Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTargetDir(WorkflowNode node, File data, String... path)	Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTargetDir(WorkflowNode node, InputStream data, String... path)	Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTempDir(WorkflowNode node, byte[] data, String... path)	Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
File	writeToTempDir(WorkflowNode node, IFileProviding<?,? extends IFileDataEntity<?>> providing, String... subDirs)	Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
default File	writeToTempDir(WorkflowNode node, File data, String... path)	Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.
File	writeToTempDir(WorkflowNode node, InputStream data, String... path)	Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file.

Method Detail

attachFilesToFormRecord

default List<Attachment> attachFilesToFormRecord(File... files)
                                          throws IOException

Attaches the given files to the current form record for which the workflow is executed. The files are attached as the UserMgmtUtils.SYSTEM user.

Parameters:

files - Files to be attached to the form record. Must not be a directory.

wfpc - Current workflow processing context.

Returns:

The attachments that were created.

Throws:

IOException - When the file data could not be read.

attachFilesToFormRecord

List<Attachment> attachFilesToFormRecord(Iterable<File> files)
                                  throws IOException

Attaches the given files to the current form record for which the workflow is executed. The files are attached as the UserMgmtUtils.SYSTEM user.

Parameters:

files - Files to be attached to the form record. Must not be a directory.

wfpc - Current workflow processing context.

Returns:

The attachments that were created.

Throws:

IOException - When the file data could not be read.

copyFilesToDir

@Deprecated
@Nullable
default File copyFilesToDir(File sourceFileOrDirectory,
                            File targetDir)
                     throws IOException

Deprecated.

Use copyFilesToDir(File, File, EFileConflictMode).

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectory - File or directory with files to copy.

targetDir - Target directory for the source files. Must be a directory and not a file.

Returns:

When the source is a file: the file object pointing to the copied file. When the source is a directory: the file object pointing to the sub directory in the target directory. null when no source or target was given, or the target is not a directory.

Throws:

IOException - When the file cannot be copied.

copyFilesToDir

@Nullable
File copyFilesToDir(File sourceFileOrDirectory,
                    File targetDir,
                    EFileConflictMode mode)
             throws IOException

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectory - File or directory with files to copy.

targetDir - Target directory for the source files. Must be a directory and not a file.

mode - How to proceed when the target file exists already.

Returns:

When the source is a file: the file object pointing to the copied file. When the source is a directory: the file object pointing to the sub directory in the target directory. null when no source or target was given, or the target is not a directory.

Throws:

IOException - When the file cannot be copied.

Since:

7.0.5

copyFilesToDir

@Deprecated
default List<File> copyFilesToDir(File[] sourceFileOrDirectories,
                                  File targetDir)
                           throws IOException

Deprecated.

Use copyFilesToDir(File[], File, EFileConflictMode).

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectories - Files or directories with files to copy.

targetDir - Target directory for the source files . Must be a directory and not a file.

Returns:

The list of copied files or directories that were written to the file system, as if copyFilesToDir(File, File) had been called on each source file separately.

Throws:

IOException - When the file cannot be copied.

copyFilesToDir

default List<File> copyFilesToDir(File[] sourceFileOrDirectories,
                                  File targetDir,
                                  EFileConflictMode mode)
                           throws IOException

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectories - Files or directories with files to copy.

targetDir - Target directory for the source files . Must be a directory and not a file.

mode - How to proceed when the target file exists already.

Returns:

The list of copied files or directories that were written to the file system, as if copyFilesToDir(File, File) had been called on each source file separately.

Throws:

IOException - When the file cannot be copied.

Since:

7.0.5

copyFilesToDir

@Deprecated
default List<File> copyFilesToDir(Iterable<File> sourceFileOrDirectories,
                                  File targetDir)
                           throws IOException

Deprecated.

Use copyFilesToDir(Iterable, File, EFileConflictMode).

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectories - Files or directories with files to copy.

targetDir - Target directory for the source files . Must be a directory and not a file.

Returns:

The list of copied files or directories that were written to the file system, as if copyFilesToDir(File, File) had been called on each source file separately.

Throws:

IOException - When the file cannot be copied.

copyFilesToDir

default List<File> copyFilesToDir(Iterable<File> sourceFileOrDirectories,
                                  File targetDir,
                                  EFileConflictMode mode)
                           throws IOException

Copies the source files to the given target directory. If the source points to a directory, all files in that directory are copied (non-recursively) to the target. The target directory and all parent directories are created when they do not exist yet.

Files in the target directory are overwritten if they exist already.

Parameters:

sourceFileOrDirectories - Files or directories with files to copy.

targetDir - Target directory for the source files . Must be a directory and not a file.

mode - How to proceed when the target file exists already.

Returns:

The list of copied files or directories that were written to the file system, as if copyFilesToDir(File, File) had been called on each source file separately.

Throws:

IOException - When the file cannot be copied.

Since:

7.0.5

copyFileTo

File copyFileTo(File sourceFile,
                File targetFile,
                EFileConflictMode mode)
         throws IOException

Copies the given file to the target directory and file name. When the the target file exists already, the file is either overwritten when the conflict mode is set to EFileConflictMode.OVERWRITE or renamed when the conflict mode is set to EFileConflictMode.RENAME. Parent directories of the target file are created if they do not exist yet.

Parameters:

sourceFile - An existing file to copy. This must point to an existing file, not a directory.

targetFile - Target to which to copy the file. This must not be an existing directory.

mode - How to proceed when the target file exists already.

Returns:

The copied file. This is identical to the target file when the conflict mode is set to EFileConflictMode.OVERWRITE.

Throws:

IOException - When the file could not be copied.

Since:

7.0.5

getAttachmentsFromUploadElements

List<Attachment> getAttachmentsFromUploadElements(List<String> uploadElements,
                                                  Vorgang formRecord,
                                                  IFormDataAdapter formDataAdapter)

Determines the upload attachments from the specified form record.

Parameters:

uploadElements - Upload elements the given action required.

formRecord - the Vorgang

formDataAdapter - a IFormDataAdapter

Returns:

a list of Attachment objects from the form record

getFilesFromPreviousNode

List<List<File>> getFilesFromPreviousNode(WorkflowNode previousNode)

Returns all files from given node. The node must have been executed already. Nodes that did not create a file or directory are omitted. Note that a node may have been executed multiple times, e.g. when it was placed in a loop.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

previousNode - Previous node for which to retrieve the files.

Returns:

A list with one item for each time the node was executed. Each item contains all files or directories that were created the specified previous nodes during that execution.

getFilesFromPreviousNodes

List<File> getFilesFromPreviousNodes(Iterable<WorkflowNode> previousNode)

Returns all files from given nodes. These nodes must have been executed already. Nodes that did not create a file or directory are omitted. When a node was executed multiple times, all files from all executions are returned.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

previousNode - Previous nodes for which to retrieve the files.

Returns:

All files or directories that were created the specified previous nodes.

getFilesFromPreviousNodes

default List<File> getFilesFromPreviousNodes(WorkflowNode... previousNodes)

Returns all files from the given previous nodes. Nodes that did not create a file or directory are omitted.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

previousNodes - Previous nodes for which to retrieve the files.

Returns:

All files or directories that were created for the specified previous nodes.

getFilesFromUploadElements

default List<IResolvedFile> getFilesFromUploadElements(IUploadConsuming consuming)
                                                throws de.xima.cmn.dao.exceptions.AbstractDaoRuntimeException,
                                                       IOException

Same as getFilesFromUploadElements(List), but takes the parameters from the given IUploadConsuming corresponding.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

consuming - Object with the upload element names for which to retrieve the files.

Returns:

List of the files that were uploaded for the given upload elements.

Throws:

de.xima.cmn.dao.exceptions.AbstractDaoRuntimeException - When the files could not be read from the database.

IOException - When the files could not be saved to the file system.

getFilesFromUploadElements

List<IResolvedFile> getFilesFromUploadElements(List<String> uploadElements)
                                        throws de.xima.cmn.dao.exceptions.AbstractDaoRuntimeException,
                                               IOException

Returns a list of all files from the given upload elements. Upload elements with no uploaded file are skipped.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

uploadElements - Upload elements the given action required. Must contain the FormElement.getAlias() of the form upload element.

Returns:

List of the files that were uploaded for the given upload elements.

Throws:

de.xima.cmn.dao.exceptions.AbstractDaoRuntimeException - When the files could not be read from the database.

IOException - When the files could not be saved to the file system.

getFileSingle

IResolvedFile getFileSingle(WorkflowNode node,
                            ISingleFileProviding singleFile,
                            IFileSearchOptions options)
                     throws MalformedURLException,
                            FileNotFoundException,
                            FileFormatException,
                            IOException,
                            IllegalArgumentException

Returns the file represented by the given descriptor. When the files of a previous node are referenced and that node was executed multiple times, all files from all executions of that node are returned.

This will throw when ISingleFileProviding.getResource() is null. If the resource is optional, check for that case before you call this method.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

node - Node that requested the files. Used to determine an appropriate temporary directory.

singleFile - File descriptor for a single file.

options - Options for searching files. When null, a reasonable default is used.

Returns:

The file represented by the given descriptor. null when no file is found.

Throws:

MalformedURLException - When a URL resource is selected an the URL is invalid.

FileNotFoundException - When the given singleFile has not resource selected; or when no matching resource could be found; such as when no file for an upload element with the configured name exists; or when the selected workflow node was not executed or does not exist anymore.

FileFormatException - When searching for an form record attachment and one is found, but it does not match the filter (extension) configured by the user.

IOException - When a file could not be read from the file system or a resource could not be read from the network.

IllegalArgumentException - When the given ISingleFileProviding is invalid (and should not have passed the workflow validation process).

getFilesMulti

IResolvedMultiFile getFilesMulti(WorkflowNode node,
                                 IMultiFileProviding multiFile,
                                 IFileSearchOptions options)
                          throws MalformedURLException,
                                 FileNotFoundException,
                                 FileFormatException,
                                 IOException,
                                 IllegalArgumentException

Returns the files represented by the given descriptor. When the files of a previous node are referenced and that node was executed multiple times, all files from all executions of that node are returned.

The returned file(s) may be shared with other node and should be though of a read-only. You may read the file(s), but should neither modify nor delete the file(s). You should also not write other files to the directory of the returned file(s), use targetDirForNode(WorkflowNode, String...) or randomTempDirForNode(WorkflowNode, String...) when you need write output our temporary files.

Parameters:

node - Node that requested the files. Used to determine an appropriate temporary directory.

multiFile - File descriptor for multiple files.

options - Options for searching files. When null, a reasonable default is used.

Returns:

The resolved multi files, with the original file names and the directory containing the files.

Throws:

MalformedURLException - When a URL resource is selected an the URL is invalid.

FileNotFoundException - When no matching resource could be found. Such as when no file for an upload element with the configured name exists; or when the selected workflow node was not executed or does not exist anymore.

FileFormatException - When searching for an form record attachment and one is found, but it does not match the filter (extension) configured by the user.

IOException - When a file could not be read from the file system or a resource could not be read from the network.

IllegalArgumentException - When the given ISingleFileProviding is invalid (and should not have passed the workflow validation process).

guessContentType

IGuessedContentType guessContentType(File file)

Parameters:

file - A file to analyze.

Returns:

The best guess for the content type of the given file. May return application/octet-stream when no better guess is available When the file could not be read or accessed, returns application/octet-stream.

guessContentType

IGuessedContentType guessContentType(String fileName,
                                     byte[] contents)

Parameters:

fileName - Name of the file, with the extension.

contents - Contents of the file to analyze.

Returns:

The best guess for the content type of the given file. May return application/octet-stream when no better guess is available.

listFiles

default List<File> listFiles(File directory,
                             boolean recursive,
                             Iterable<String> extensions)
                      throws IOException

Lists all files contained in the given directory. If the given directory is a File.isFile(), a singleton list with that file is returned. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directory - Directory with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

listFiles

List<File> listFiles(File directory,
                     boolean recursive,
                     String... extensions)
              throws IOException

Lists all files contained in the given directory. If the given directory is a File.isFile(), a singleton list with that file is returned. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directory - Directory with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

listFiles

default List<File> listFiles(File[] directories,
                             boolean recursive,
                             Iterable<String> extensions)
                      throws IOException

Lists all files contained in the given directories. Duplicate files are excluded in the returned list .If a given directory is a File.isFile(), that file is returned in the resulting list. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directories - Directories with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

listFiles

default List<File> listFiles(File[] directories,
                             boolean recursive,
                             String... extensions)
                      throws IOException

Lists all files contained in the given directories. Duplicate files are excluded in the returned list .If a given directory is a File.isFile(), that file is returned in the resulting list. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directories - Directories with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

listFiles

default List<File> listFiles(Iterable<File> directories,
                             boolean recursive,
                             Iterable<String> extensions)
                      throws IOException

Lists all files contained in the given directories. Duplicate files are excluded in the returned list .If a given directory is a File.isFile(), that file is returned in the resulting list. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directories - Directories with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

listFiles

List<File> listFiles(Iterable<File> directories,
                     boolean recursive,
                     String... extensions)
              throws IOException

Lists all files contained in the given directories. Duplicate files are excluded in the returned list .If a given directory is a File.isFile(), that file is returned in the resulting list. If recursive is enabled, this method walks all directories recursively and only returns the files they contain.

Parameters:

directories - Directories with files to list.

recursive - true to list files in sub directories, false to list only the immediate content of the given directory.

extensions - A list of extensions by which to filter the returned files. When null or empty, all files are returned.

Returns:

All files in the given directory, empty list if no files are found.

Throws:

IOException - When the contents of the directory could not be read.

randomSourceDirForNode

default File randomSourceDirForNode(WorkflowNode node,
                                    String... subDirs)
                             throws IOException

Creates a random temporary directory inside the given source directory of the node. This may be used by generic helper methods that need to create a different directory each time they are called. This is essentially the same as creating a random temporary directory inside the directory returned by sourceDirForNode(WorkflowNode, String...)

Parameters:

node - The node for which the temporary directory should be returned.

subDirs - Optional path segments to access a sub directory.

Returns:

A random temporary directory inside the directory for the given processed item, or a sub directory if subDirs is given.

Throws:

IOException - When the the target directory could not be acquired or created.

See Also:

To find nodes, use the node locator IAdvancedWorkflowContext#node()

randomTargetDirForNode

default File randomTargetDirForNode(WorkflowNode node,
                                    String... subDirs)
                             throws IOException

Creates a random temporary directory inside the given target directory of the node. This may be used by generic helper methods that need to create a different directory each time they are called. This is essentially the same as creating a random temporary directory inside the directory returned by targetDirForNode(WorkflowNode, String...)

Parameters:

node - The node for which the temporary directory should be returned.

subDirs - Optional path segments to access a sub directory.

Returns:

A random temporary directory inside the directory for the given processed item, or a sub directory if subDirs is given.

Throws:

IOException - When the the target directory could not be acquired or created.

See Also:

To find nodes, use the node locator IAdvancedWorkflowContext#node()

randomTempDirForNode

File randomTempDirForNode(WorkflowNode node,
                          String... subDirs)
                   throws IOException

Creates a random temporary directory inside the given sub directory for the node. This may be used by generic helper methods that need to create a different directory each time they are called. This is essentially the same as creating a random temporary directory inside the directory returned by tempDirForNode(WorkflowNode, String...)

Parameters:

node - The node for which the temporary directory should be returned.

subDirs - Optional path segments to access a sub directory.

Returns:

A random temporary directory inside the directory for the given processed item, or a sub directory if subDirs is given.

Throws:

IOException - When the the target directory could not be acquired or created.

See Also:

To find nodes, use the node locator IAdvancedWorkflowContext#node()

sanitizeFilename

default String sanitizeFilename(String fileName)

Parameters:

fileName - A possibly unsafe name (such as user input) that you would like to use as a filename.

Returns:

A safe filename that can be used to create a new file on the file system. It is only a file name without a any path separators.

See Also:

tempDirForNode(WorkflowNode, String...)

sanitizeFilename

String sanitizeFilename(String fileName,
                        IPlaceholderEscaper placeholderEscaper)

Parameters:

fileName - A possibly unsafe name (such as user input) that you would like to use as a filename.

placeholderEscaper - When null, no placeholders are escaped. When not null, placeholders are escaped and this parameters indicates how placeholders are inserted into the text body.

Returns:

A safe filename that can be used to create a new file on the file system. It is only a file name without a any path separators.

See Also:

tempDirForNode(WorkflowNode, String...)

sourceDirForNode

default File sourceDirForNode(WorkflowNode node,
                              String... subDirs)
                       throws IOException

Shortcut for getTempDirForNode(node, "source"). The default directory for storing intermediate files that are required only during execution of the node, but are not returned and made available to other nodes.

Parameters:

node - The node for which the source directory should be returned.

subDirs - Optional path segments to access a sub directory or the source directory.

Returns:

The temporary source directory for the given node, a sub directory of the node's temporary directory.

Throws:

IOException - When intermediate non-existing directories could not be created.

sourceFileForNode

default File sourceFileForNode(WorkflowNode node,
                               String... subDirs)
                        throws IOException

Shortcut for getTempFileForNode(node, "source"). Creates a file in the default directory for storing intermediate files that are required only during execution of the node, but are not returned and made available to other nodes.

Compared with sourceDirForNode(WorkflowNode, String...), this method interprets the last item of subDirs as a file and does not attempt to create a directory for that. E.g. if you call sourceDirForNode(node, "foo", "bar.txt", it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

node - The node for which the source directory should be returned.

subDirs - Optional path segments to access a sub directory or the source directory.

Returns:

A file within the the temporary source directory for the given node.

Throws:

IOException - When intermediate non-existing directories could not be created.

subDirectory

File subDirectory(File baseDir,
                  String... subDirs)
           throws IOException

Starting at the given base directory, accesses the given sub directories, creates that sub directory if necessary, and returns a file corresponding to that sub directory.

Each item in the given sub directory is sanitized and should not contain path separators or relative paths. When the subDirs contains n non-empty items, it is guaranteed that the baseDir is the nth parent of the returned directory. So for example:

 // "/tmp/foo"
 subDirectory("/tmp", "foo");
 
 // "/tmp/bar"
 subDirectory("/tmp", "../bar");
 
 // "/tmp/bar/baz"
 subDirectory("/tmp", "../bar", "baz");
 

Parameters:

baseDir - Base directory.

subDirs - A list of sub directories. Should be an absolute path. Empty names are ignored, e.g. passing ["foo", "", "bar] is the same as passing ["foo", "bar].

Returns:

The file pointing to the path corresponding to <dir>/subDirs[0]/subDirs[1]/.../subDirs[len - 1]. Non-existing directories will be created.

Throws:

IOException - When the sub directory could not be created.

subDirectory

default File subDirectory(File baseDir,
                          Iterable<String> subDirs)
                   throws IOException

Starting at the given base directory, accesses the given sub directories, creates that sub directory if necessary, and returns a file corresponding to that sub directory.

Each item in the given sub directory is sanitized and should not contain path separators or relative paths. When the subDirs contains n non-empty items, it is guaranteed that the baseDir is the nth parent of the returned directory. So for example:

 // "/tmp/foo"
 subDirectory("/tmp", "foo");
 
 // "/tmp/bar"
 subDirectory("/tmp", "../bar");
 
 // "/tmp/bar/baz"
 subDirectory("/tmp", "../bar", "baz");
 

Parameters:

baseDir - Base directory.

subDirs - A list of sub directories. Should be an absolute path. Empty names are ignored, e.g. passing ["foo", "", "bar] is the same as passing ["foo", "bar].

Returns:

The file pointing to the path corresponding to <dir>/subDirs[0]/subDirs[1]/.../subDirs[len - 1]. Non-existing directories will be created.

Throws:

IOException - When the sub directory could not be created.

subFile

File subFile(File baseDir,
             String... subDirs)
      throws IOException

Similar to subDirectory(File, String...), but with the different that this method does not create a directory for the last item in the given subDirs. So if you call subDir("path/to/base/dir". "foo", "bar.txt, it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

baseDir - The base directory. Should be an absolute path.

subDirs - A list of sub directories to access or create in the base directory. Empty names are ignored, e.g. passing ["foo", "", "bar] is the same as passing ["foo", "bar].

Returns:

The file pointing to the path corresponding to <dir>/subDirs[0]/subDirs[1]/.../subDirs[len - 1]. Non-existing directories will be created (except for the last item in the given subDirs).

Throws:

IOException - When the sub directory could not be created.

subFile

default File subFile(File baseDir,
                     Iterable<String> subDirs)
              throws IOException

Similar to subDirectory(File, String...), but with the different that this method does not create a directory for the last item in the given subDirs. So if you call subDir("path/to/base/dir". "foo", "bar.txt, it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

baseDir - The base directory. Should be an absolute path.

subDirs - A list of sub directories to access or create in the base directory. Empty names are ignored, e.g. passing ["foo", "", "bar] is the same as passing ["foo", "bar].

Returns:

The file pointing to the path corresponding to <dir>/subDirs[0]/subDirs[1]/.../subDirs[len - 1]. Non-existing directories will be created (except for the last item in the given subDirs).

Throws:

IOException - When the sub directory could not be created.

targetDirForNode

default File targetDirForNode(WorkflowNode node,
                              String... subDirs)
                       throws IOException

Shortcut for getTempDirForNode(node, "target"). The default directory for storing files that are returned and made available to other nodes.

Parameters:

node - The node for which the target directory should be returned.

subDirs - Optional path segments to access a sub directory or the target directory.

Returns:

The temporary source directory for the given node, a sub directory of the node's temporary directory.

Throws:

IOException - When intermediate non-existing directories could not be created.

targetFileForNode

default File targetFileForNode(WorkflowNode node,
                               String... subDirs)
                        throws IOException

Shortcut for getTempFileForNode(node, "target"). The default directory for storing files that are returned and made available to other nodes.

Compared with targetDirForNode(WorkflowNode, String...), this method interprets the last item of subDirs as a file and does not attempt to create a directory for that. E.g. if you call targetDirForNode(node, "foo", "bar.txt", it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

node - The node for which the target directory should be returned.

subDirs - Optional path segments to access a sub directory or the target directory.

Returns:

A file within the temporary source directory for the given node.

Throws:

IOException - When intermediate non-existing directories could not be created.

tempDirForNode

File tempDirForNode(WorkflowNode node,
                    String... subDirs)
             throws IOException

Path to the temporary target directory for the given workflow node. This directory may be used to store files created by the workflow node. The directory path that is returned points to a directory that exists on the file system (if necessary, it is created when calling this method). The directory will be deleted once execution of the workflow finishes.

Parameters:

node - The node for which the temporary directory should be returned.

subDirs - Optional path segments to access a sub directory.

Returns:

The directory for the given processed item, or a sub directory if subDirs is given.

Throws:

IOException - When the the target directory could not be acquired or created.

See Also:

To find nodes, use the node locator IAdvancedWorkflowContext#node()

tempDirShared

File tempDirShared(String... subDirs)
            throws IOException

Return a path to the temporary directory shared by all workflow nodes. Usually you should not be using this, use tempDirForNode(WorkflowNode, String...) instead.

Parameters:

subDirs - Optional path segments to access a sub directory, or a sub directory if subDirs is given.

Returns:

Temporary directory for the current workflow execution.

Throws:

IOException - When intermediate non-existing directories could not be created.

tempFileForNode

File tempFileForNode(WorkflowNode node,
                     String... subDirs)
              throws IOException

Returns the path to a file in the temporary target directory for the given workflow node. This directory may be used to store files created by the workflow node. The directory path that is returned points to a directory that exists on the file system (if necessary, it is created when calling this method). The directory will be deleted once execution of the workflow finishes.

Compared with tempDirForNode(WorkflowNode, String...), this method interprets the last item of subDirs as a file and does not attempt to create a directory for that. E.g. if you call tempDirForNode(node, "foo", "bar.txt", it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

node - The node for which the temporary directory should be returned.

subDirs - Optional path segments to access a sub directory.

Returns:

A file within the directory for the given processed item.

Throws:

IOException - When the the target directory could not be acquired or created.

See Also:

To find nodes, use the node locator IAdvancedWorkflowContext#node()

tempFileShared

File tempFileShared(String... subDirs)
             throws IOException

Return a file within to the temporary directory shared by all workflow nodes. Usually you should not be using this, use tempDirForNode(WorkflowNode, String...) instead.

Compared with tempDirShared(String...), this method interprets the last item of subDirs as a file and does not attempt to create a directory for that. E.g. if you call tempDirShared("foo", "bar.txt", it would attempt to create the directories foo and bar.txt. This method only creates the node directory.

Parameters:

subDirs - Optional path segments to access a sub directory, or a sub directory if subDirs is given.

Returns:

Temporary directory for the current workflow execution.

Throws:

IOException - When intermediate non-existing directories could not be created.

withExtension

File withExtension(File file,
                   String newExtension)

Changes the extension of the file name to the given extension.

Parameters:

file - Input file for which to change the extension.

newExtension - New extension for the file. When this is empty, the extension is removed. May or may not start with a period.

Returns:

A new file object with the path and name, but with the extension changed to the given new extension.

withExtension

String withExtension(String fileName,
                     String newExtension)

Changes the extension of the file name to the given extension.

Parameters:

fileName - Input file name for which to change the extension.

newExtension - New extension for the file. When this is empty, the extension is removed. May or may not start with a period.

Returns:

A new file name with the path and name, but with the extension changed to the given new extension.

writeToSourceDir

default File writeToSourceDir(WorkflowNode node,
                              byte[] data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the source directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToSourceDir

default File writeToSourceDir(WorkflowNode node,
                              File data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the source directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToSourceDir

default File writeToSourceDir(WorkflowNode node,
                              IFileProviding<?,? extends IFileDataEntity<?>> providing,
                              String... subDirs)
                       throws IOException,
                              de.xima.cmn.dao.exceptions.ReadException

Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose source directory is used to create the file.

providing - An instance that provides the binary data to write to the file system.

subDirs - Optional sub directories in temporary directory where the file is written. The file name is taken from the given providing.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

de.xima.cmn.dao.exceptions.ReadException - When the data could not be read from the database.

writeToSourceDir

default File writeToSourceDir(WorkflowNode node,
                              InputStream data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the sourceDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the source directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTargetDir

default File writeToTargetDir(WorkflowNode node,
                              byte[] data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the target directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTargetDir

default File writeToTargetDir(WorkflowNode node,
                              File data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the target directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTargetDir

default File writeToTargetDir(WorkflowNode node,
                              IFileProviding<?,? extends IFileDataEntity<?>> providing,
                              String... subDirs)
                       throws IOException,
                              de.xima.cmn.dao.exceptions.ReadException

Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose target directory is used to create the file.

providing - An instance that provides the binary data to write to the file system.

subDirs - Optional sub directories in temporary directory where the file is written. The file name is taken from the given providing.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

de.xima.cmn.dao.exceptions.ReadException - When the data could not be read from the database.

writeToTargetDir

default File writeToTargetDir(WorkflowNode node,
                              InputStream data,
                              String... path)
                       throws IOException

Writes the given binary data to a file in the targetDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the target directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTempDir

default File writeToTempDir(WorkflowNode node,
                            byte[] data,
                            String... path)
                     throws IOException

Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the temporary directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTempDir

default File writeToTempDir(WorkflowNode node,
                            File data,
                            String... path)
                     throws IOException

Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the temporary directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

writeToTempDir

File writeToTempDir(WorkflowNode node,
                    IFileProviding<?,? extends IFileDataEntity<?>> providing,
                    String... subDirs)
             throws IOException,
                    de.xima.cmn.dao.exceptions.ReadException

Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

providing - An instance that provides the binary data to write to the file system.

subDirs - Optional sub directories in temporary directory where the file is written. The file name is taken from the given providing.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.

de.xima.cmn.dao.exceptions.ReadException - When the data could not be read from the database.

writeToTempDir

File writeToTempDir(WorkflowNode node,
                    InputStream data,
                    String... path)
             throws IOException

Writes the given binary data to a file in the tempDirForNode(WorkflowNode, String...) of the given node, and returns a file pointing to the newly created file. When a file with the name exists already in the given directory, creates a file name that does not exist yet.

Parameters:

node - The node whose temporary directory is used to create the file.

path - Desired path in the temporary directory where the file is created (should end on a file name). The file name may be changed if a file with the same name exists already.

data - The binary data to write to the file system.

Returns:

The file pointing to the newly created file with the given binary data.

Throws:

IOException - When the file could not be created.