File

Purpose¶

New Feature

Since 6.10.7

Enables the writing, reading, and manipulation of files and directories.

Intended to replace the use of FileUtils Methods, examples allow comparison to legacy implementations.

Optional params are provided using a closure, else defaults will be used.

Methods¶

Binding name: p6.file

New Feature

Since 6.10.15

If the target file or folder path is relative, it will be relative to P6CORE_DATA.

Example

Path	Resolved Path
relative/path/to/folder	/opt/p6core.data/relative/path/to/folder
/absolute/path/to/folder	/absolute/path/to/folder
file://path/to/folder	/path/to/folder
p6file://${P6_DATA}/path/to/folder	//opt/p6core.data/path/to/folder

write¶

Write a String or Byte Array to a file.
Returns true on completion without error.

Optional params:

^{Params: String - charset, Boolean - append, Boolean - override}
^{Default: charset = UTF-8, append = false, override = true}

override determines if an existing file should be overwritten.
append determines if the provided data should be appended to contents of an existing file.

Syntax

Boolean p6.file.write String data to String filepath

Boolean p6.file.write byte[] data to String filepath

Boolean p6.file.write InputStream data to String filepath

Example

=== “New”

def csvData = 'InvoiceNumber,Amount,Currency\nINV-2024-0042,1250.00,EUR'

p6.file.write csvData to 'p6file://${P6_DATA}/resources/exports/invoices.csv'
p6.file.write csvData to 'p6file://${P6_DATA}/resources/exports/invoices.csv', {
    charset 'UTF-8'
    append true
}

=== “Legacy”

// Write a string
FileUtils.writeStringToFile(data, new File('/opt/p6core.data/resources/exports/invoices.csv'));
// Both syntaxes are valid for the File constructor
FileUtils.writeStringToFile(data, new File('p6file:///opt/p6core.data/resources/exports/invoices.csv'));
// Write a byte array
FileUtils.writeByteArrayToFile(data, new File('/opt/p6core.data/resources/exports/invoices.csv'));
// Append a string
FileUtils.writeStringToFile(data, new File('/opt/p6core.data/resources/exports/invoices.csv', true));

readText¶

Read the contents of a file as a String.

optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

String p6.file.readText String filepath

Example

NewLegacy

String invoiceCsv = p6.file.readText 'p6file://${P6_DATA}/resources/imports/invoices.csv'
// With custom Charset
String invoiceCsv = p6.file.readText 'p6file://${P6_DATA}/resources/imports/invoices.csv', {charset 'UTF-16'}

String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'))
// With custom Charset
String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'), 'UTF-16')

readJson¶

Read the contents of a file as a JSON object. As if as using a JsonSlurper.

Optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

Object p6.file.readJson String filepath

Example

NewLegacy

def config = p6.file.readJson 'p6file://${P6_DATA}/resources/config/mapping.json'
// With custom Charset
def config = p6.file.readJson 'p6file://${P6_DATA}/resources/config/mapping.json', {charset 'UTF-16'}

String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'))
// Or if with custom charset
String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'), 'UTF-16')
// Then 
def fileContents = new JsonSlurper().parseText(fileText)

readXml¶

Read the contents of a file as a GPathResult object. As if using an XmlSlurper. Allows use of non-default XmlSlurper by specifying behaviour for validation, namespace-awareness, and Doctype declaration.

Optional params:

^{Params: String - charset, Boolean - validating, Boolean - namespaceAware, Boolean - allowDocTypeDeclaration}
^{Default: charset = UTF-8, validating = false, namespaceAware = true, allowDocTypeDeclaration = false, features = null}

Syntax

GPathResult p6.file.readXml String filepath

Example

NewLegacy

GPathResult invoice = p6.file.readXml 'p6file://${P6_DATA}/resources/documents/invoice.xml'
// Or if with custom charset
GPathResult invoice = p6.file.readXml 'p6file://${P6_DATA}/resources/documents/invoice.xml', {charset 'UTF-16'}
// To specify alternate behaviour
GPathResult invoice = p6.file.readXml 'p6file://${P6_DATA}/resources/documents/invoice.xml', {
    validating true
    namespaceAware false
    allowDocTypeDeclaration true
}
// To use the setFeature method
Map<String, Boolean> featuresToSet = ['Feature1': false, 'feature2': true]
GPathResult invoice = p6.file.readXml 'p6file://${P6_DATA}/resources/documents/invoice.xml', {
    features featuresToSet
}

String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'))
// Or if with custom charset
String fileText = FileUtils.readFileToString(new File('p6file://${P6_DATA}/resources/data/file.txt'), 'UTF-16')
// Then 
GPathResult fileContents = new XmlSlurper().parseText(fileText)

readToBase64¶

Read the contents of a file as a base64 encoded String.

Optional params:

^{Params: String - charset}
^{Default: charset = UTF-8}

Syntax

String p6.file.readBase64 String filepath

Example

NewLegacy

String encodedPdf = p6.file.readBase64 'p6file://${P6_DATA}/resources/reports/monthly.pdf'
// Or if with custom charset
String encodedPdf = p6.file.readBase64 'p6file://${P6_DATA}/resources/reports/monthly.pdf', {charset 'UTF-16'}

byte[] fileBytes = FileUtils.readFileToByteArray(new File('p6file://${P6_DATA}/resources/data/file.txt'))
// Or if with custom charset
byte[] fileBytes = FileUtils.readFileToByteArray(new File('p6file://${P6_DATA}/resources/data/file.txt'), 'UTF-16')
// Then
byte[] encodedBytes = Base64.encodeBase64(fileBytes);
String fileContents = new String(encodedBytes, charset)

move¶

Moves the File or Folder from source location to destination.
Returns true on completion without error.
Will error if destination file/folder exists unless override is set to true.

Optional params:

^{Params: Boolean - override}
^{Default: override = false}

Syntax

Boolean p6.file.move String source to String destination

Example

NewLegacy

p6.file.move 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml'
// Or to change override behaviour
p6.file.move 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml', {override true}

// For file
FileUtils.moveFile('p6file://${P6_DATA}/resources/data/file.txt', 'p6file://${P6_DATA}/resources/archive/order.xml')
// For directory
FileUtils.moveDirectory('Path/To/SourceDirectory', 'Path/To/DestDirectory')
// To overwrite existing
FileUtils.moveFile('p6file://${P6_DATA}/resources/data/file.txt', 'p6file://${P6_DATA}/resources/archive/order.xml', StandardCopyOption.REPLACE_EXISTING)

copy¶

Copies the File or Folder from source location to destination.
Returns true on completion without error.

Optional params:

^{Params: Boolean - override}
^{Default: override = true}

Syntax

Boolean p6.file.copy String source to String destination

Example

NewLegacy

p6.file.copy 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml'
// Or to change override behaviour
p6.file.copy 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml', {override true}

// For file
FileUtils.copyFile('p6file://${P6_DATA}/resources/data/file.txt', 'p6file://${P6_DATA}/resources/archive/order.xml')
// For directory
FileUtils.copyDirectory('Path/To/SourceDirectory', 'Path/To/DestDirectory')
// No override equivalent for  FileUtils copy methods, legacy would check for existing files and not copy if they exist

delete¶

Delete the File or Folder at filepath given.
Returns true on completion without error.

Syntax

Boolean p6.file.delete String source

Example

NewLegacy

p6.file.delete 'p6file://${P6_DATA}/resources/data/file.txt'

// For file
FileUtils.deleteFile('p6file://${P6_DATA}/resources/data/file.txt')
// For directory
FileUtils.deleteDirectory('Path/To/Directory')

cleanFolder¶

Deprecated

Since 6.10.7, this method has been moved to the p6.file.folder clean

Empties the contents of a directory. Canonical to deleting, and recreation of the folder.

Syntax

Boolean p6.file.cleanFolder 'p6file://${P6_DATA}/resources/temp'

Example

p6.file.cleanFolder 'p6file://${P6_DATA}/resources/temp'

permissions¶

New Feature

Since 6.10.8

Set the permissions of a file or directory. When setting permissions on a directory, the recursive parameter can be used to set permissions on all files and directories within the directory.

Syntax

Boolean p6.file.permissions 'p6file://${P6_DATA}/resources/temp', { perms 'rwxr-xr-x' }

Example

p6.file.permissions 'p6file://${P6_DATA}/resources/temp', { perms 'rwxr-xr-x' }
p6.file.permissions 'p6file://${P6_DATA}/resources/temp', { perms 'rwxr-xr-x'; recursive false}
p6.file.permissions 'p6file://${P6_DATA}/resources/temp/File', { perms 'rwxr-xr-x'}

Tip

The perms parameter must be a valid Unix permission string. For more information on Unix permission strings, refer to this guide. The recursive parameter is optional and defaults to true.

folder¶

New Feature

Since 6.10.15

Allow folder manipulation.

Syntax

Create FolderCreate temp folderClean Folder

File p6.file.folder.create 'p6file://${P6_DATA}/resources/temp'

File p6.file.folder.createTemp 'Prefix'

Remove of the sub items of the folder, but not the folder itself.

Boolean p6.file.folder.clean 'p6file://${P6_DATA}/resources/temp'

Example

Create FolderCreate temp folderClean Folder

final folder = p6.file.folder.create 'p6file://${P6_DATA}/resources/temp'

final folder = p6.file.folder.createTemp 'import-'

final success =  p6.file.folder.clean 'p6file://${P6_DATA}/resources/temp'

create¶

New Feature

Since 6.10.15

Create a file.

Syntax

File p6.file.create 'p6file://${P6_DATA}/resources/output/report'

Example

final file = p6.file.create 'p6file://${P6_DATA}/resources/data/file.txt'

createTemp¶

New Feature

Since 6.10.15

Create a temporary file.

Syntax

File p6.file.createTemp 'Prefix', 'Suffix'

Example

final file = p6.file.createTemp('extract', '.pdf')

Examples¶

To append the string “appended string” to the contents of a file, in charset UTF-16

Example

p6.file.write 'appended string' to 'p6file://${P6_DATA}/resources/data/file.txt', {
charset 'UTF-16'
append true
}

To move a file, overwriting any existing file.

Example

p6.file.move 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml', {override true}

To copy a file, without overwriting any existing file.

Example

p6.file.copy 'p6file://${P6_DATA}/resources/inbox/order.xml' to 'p6file://${P6_DATA}/resources/archive/order.xml', {override false}