Package io.toro.martini

Class FileMethods

java.lang.Object

io.toro.martini.FileMethods

public final class FileMethods
extends Object

Provides one-liners for performing file operations.

Constructor Summary

Constructors

Constructor	Description
FileMethods(Path packagesHomePath)

Method Summary

Modifier and Type	Method	Description
static int	copy(InputStream inputStream, OutputStream outputStream, GloopExecutionContext context)	Copies bytes from a large (over 2GB) InputStream to an OutputStream.
static long	copyLarge(InputStream inputStream, OutputStream outputStream, GloopExecutionContext context)	Copies bytes from a large (over 2GB) InputStream to an OutputStream.
static GloopModel	getTextFileInputCursor(InputStream flatFileData, String encoding, String recordSeparator, GloopExecutionContext context)	Read an InputStream and return a Gloop cursor for reading from the resource.
static OutputStream	outputStream(GloopExecutionContext context, String file, boolean mkDirs, String... openOptions)	Opens or creates a package file, returning an output stream that may be used to write bytes to the file.
static OutputStream	packageOutputStream(GloopExecutionContext context, String file, String packageName, boolean mkDirs, String... openOptions)	Opens or creates a package file, returning an output stream that may be used to write bytes to the file.
static OutputStream	packageOutputStream(String file, String packageName, boolean mkDirs, OpenOption... openOption)	Opens or creates a package file, returning an output stream that may be used to write bytes to the file.
static String	readAllContent(String resource, String packageName)	Attempt to read a resource from the selected package context, returning an String object to read from the resource.
static Stream<String>	readContent(String resource, String packageName)	Attempt to read a resource from the selected package context, returning a Stream object to read from the resource.
static void	readContent(String packageName, String resource, Closure<String> closure)	Attempt to read a resource from the selected package context and executes the closure for every line of the resource content.
static GloopModel	readFileAsMultipart(String filePath, String contentType)	Wrap a file path and return a multi-part GloopModel.
static GloopModel	readLines(String resource, String packageName, String encoding, String lineSeparator, GloopExecutionContext context)	Read a resource file residing in a Martini package and return a Gloop cursor for said file.
static GloopModel	readPackageFileAsMultipart(String resourceName, String packageName, String contentType)	Wrap a resource from a Martini package and return a multi-part GloopModel.
static Path	resource(String resource, String packageName)	Open a resource from the specified package context, returning a Path to read from the resource.
static InputStream	resourceStream(String resource, String packageName)	Open a resource from a specified package, returning an InputStream to read from the resource.
static InputStream	resourceStream(String resource, String packageName, GloopExecutionContext context)	Open a resource from a specified package, returning an InputStream to read from the resource.
static void	write(byte[] data, String file, boolean mkDirs)	Write a byte[] to a specified destination.
static void	write(InputStream data, String file, boolean mkDirs)	Write data from an InputStream to a specified destination.
static void	writeToPackage(byte[] data, String file, String packageName, boolean mkDirs)	Write a byte[] to a specified destination inside a Martini package.
static void	writeToPackage(InputStream data, String file, String packageName, boolean mkDirs)	Write an InputStream to a specified destination inside a Martini package.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileMethods

public FileMethods(Path packagesHomePath)

Method Detail

resourceStream

public static final InputStream resourceStream(@GloopParameter(allowNull=false)
                                               String resource,
                                               String packageName,
                                               GloopExecutionContext context)
                                        throws IOException

Open a resource from a specified package, returning an InputStream to read from the resource. The stream will not be buffered, and is not required to support the mark or reset methods. The stream will be safe for access by multiple concurrent threads.

Parameters:

packageName - the name of the package; if empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

context - the execution context (e.g. conf/package.xml)

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

resourceStream

public static final InputStream resourceStream(String resource,
                                               String packageName)
                                        throws IOException

Open a resource from a specified package, returning an InputStream to read from the resource. The stream will not be buffered, and is not required to support the mark or reset methods. The stream will be safe for access by multiple concurrent threads.

Parameters:

packageName - the name of the package; if empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

copyLarge

public static long copyLarge(@GloopParameter(allowNull=false)
                             InputStream inputStream,
                             @GloopParameter(allowNull=false)
                             OutputStream outputStream,
                             GloopExecutionContext context)
                      throws IOException

Copies bytes from a large (over 2GB) InputStream to an OutputStream.

This method buffers the input internally, so there is no need to use a BufferedInputStream. The buffer size is given by IOUtils.DEFAULT_BUFFER_SIZE.

Parameters:

inputStream - the InputStream to read from

outputStream - the OutputStream to write to

Returns:

the number of bytes copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.0

copy

public static int copy(@GloopParameter(allowNull=false)
                       InputStream inputStream,
                       @GloopParameter(allowNull=false)
                       OutputStream outputStream,
                       GloopExecutionContext context)
                throws IOException

Copies bytes from a large (over 2GB) InputStream to an OutputStream.

This method buffers the input internally, so there is no need to use a BufferedInputStream.

Large streams (over 2GB) will return a bytes copied value of -1 after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams, use the IOUtils.copyLarge(InputStream, OutputStream) method.

Parameters:

inputStream - the InputStream to read from

outputStream - the OutputStream to write to

Returns:

the number of bytes copied, or -1 if greater than Integer.MAX_VALUE

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.0

packageOutputStream

public static OutputStream packageOutputStream(String file,
                                               String packageName,
                                               boolean mkDirs,
                                               OpenOption... openOption)
                                        throws IOException

Opens or creates a package file, returning an output stream that may be used to write bytes to the file. The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads. Whether the returned stream is asynchronously closeable and/or interruptible is highly file system provider specific and therefore not specified.

This method opens or creates a file in exactly the manner specified by the newByteChannel method with the exception that the READ option may not be present in the array of options. If no options are present then this method works as if the CREATE, TRUNCATE_EXISTING, and WRITE options are present. In other words, it opens the file for writing, creating the file if it doesn't exist, or initially truncating an existing regular-file to a size of 0 if it exists.

Parameters:

file - the file path string

packageName - package to write the file in; if this is empty, the current package context is selected

mkDirs - flag for creating the parent directories of the file

openOption - options specifying how the file is opened

Returns:

a new OutputStream

Throws:

IllegalArgumentException - if options contains an invalid combination of options

UnsupportedOperationException - if an unsupported option is specified

IOException - if an I/O error occurs

SecurityException - In the case of the default provider, and a security manager is installed, the checkWrite method is invoked to check write access to the file. The checkDelete method is invoked to check delete access if the file is opened with the DELETE_ON_CLOSE option.

Since:

1.0

packageOutputStream

public static OutputStream packageOutputStream(GloopExecutionContext context,
                                               @GloopParameter(allowNull=false)
                                               String file,
                                               String packageName,
                                               @GloopParameter(allowNull=false,defaultValue="true")
                                               boolean mkDirs,
                                               @GloopParameter(allowNull=true,allowOtherValues=false,choices={"WRITE","APPEND","TRUNCATE_EXISTING","CREATE","CREATE_NEW","DELETE_ON_CLOSE","SPARSE","SYNC","DSYNC"})
                                               String... openOptions)
                                        throws IOException

Opens or creates a package file, returning an output stream that may be used to write bytes to the file. The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads. Whether the returned stream is asynchronously closeable and/or interruptible is highly file system provider specific and therefore not specified.

This method opens or creates a file in exactly the manner specified by the newByteChannel method with the exception that the READ option may not be present in the array of options. If no options are present then this method works as if the CREATE, TRUNCATE_EXISTING, and WRITE options are present. In other words, it opens the file for writing, creating the file if it doesn't exist, or initially truncating an existing regular-file to a size of 0 if it exists.

Parameters:

context - the execution context

file - the file path string

packageName - package to write the file in; if this is empty, the current package context is selected

mkDirs - flag for creating the parent directories of the file

openOptions - options specifying how the file is opened

Returns:

a new OutputStream

Throws:

IOException - if an I/O error occurs

Since:

1.0

outputStream

public static OutputStream outputStream(GloopExecutionContext context,
                                        @GloopParameter(allowNull=false,value="filePath in string")
                                        String file,
                                        @GloopParameter(allowNull=false,defaultValue="true",value="create the parent directories of the file. Default is true")
                                        boolean mkDirs,
                                        @GloopParameter(allowNull=true,value="options specifying how the file is opened",allowOtherValues=false,choices={"WRITE","APPEND","TRUNCATE_EXISTING","CREATE","CREATE_NEW","DELETE_ON_CLOSE","SPARSE","SYNC","DSYNC"})
                                        String... openOptions)
                                 throws IOException

Opens or creates a package file, returning an output stream that may be used to write bytes to the file. The resulting stream will not be buffered. The stream will be safe for access by multiple concurrent threads. Whether the returned stream is asynchronously closeable and/or interruptible is highly file system provider specific and therefore not specified.

This method opens or creates a file in exactly the manner specified by the newByteChannel method with the exception that the READ option may not be present in the array of options. If no options are present then this method works as if the CREATE, TRUNCATE_EXISTING, and WRITE options are present. In other words, it opens the file for writing, creating the file if it doesn't exist, or initially truncating an existing regular-file to a size of 0 if it exists.

Parameters:

context - the execution context

file - the file path string

mkDirs - flag for creating the parent directories of the file

openOptions - options specifying how the file is opened

Returns:

a new OutputStream

Throws:

IOException - if an I/O error occurs

Since:

1.0

write

public static void write(@GloopParameter(allowNull=false)
                         byte[] data,
                         @GloopParameter(allowNull=false)
                         String file,
                         @GloopParameter(allowNull=false,defaultValue="true")
                         boolean mkDirs)
                  throws IOException

Write a byte[] to a specified destination.

Parameters:

data - the byte array to write; do not modify during output

file - where to write the bytes

mkDirs - flag for creating the parent directories of the file

Throws:

NullPointerException - if output is null

IOException - if an I/O error occurs

Since:

1.0

write

public static void write(@GloopParameter(allowNull=false)
                         InputStream data,
                         @GloopParameter(allowNull=false)
                         String file,
                         @GloopParameter(allowNull=false,defaultValue="true")
                         boolean mkDirs)
                  throws IOException

Write data from an InputStream to a specified destination.

Parameters:

data - the InputStream to read from

file - where to write the data

mkDirs - flag for creating the parent directories of the file

Throws:

NullPointerException - if output is null

IOException - if an I/O error occurs

Since:

1.0

writeToPackage

public static void writeToPackage(@GloopParameter(allowNull=false)
                                  byte[] data,
                                  @GloopParameter(allowNull=false)
                                  String file,
                                  String packageName,
                                  @GloopParameter(allowNull=false,defaultValue="true")
                                  boolean mkDirs)
                           throws IOException

Write a byte[] to a specified destination inside a Martini package.

Parameters:

data - the byte array to write; do not modify during output

file - where to write the data

packageName - package to write the file in; if this is empty, the current package context is selected

mkDirs - flag for creating the parent directories of the file

Throws:

NullPointerException - if output is null

IOException - if an I/O error occurs

Since:

1.0

writeToPackage

public static void writeToPackage(@GloopParameter(allowNull=false)
                                  InputStream data,
                                  @GloopParameter(allowNull=false)
                                  String file,
                                  String packageName,
                                  @GloopParameter(allowNull=false,defaultValue="true")
                                  boolean mkDirs)
                           throws IOException

Write an InputStream to a specified destination inside a Martini package.

Parameters:

data - the InputStream to read from

file - where to write the data

packageName - package to write the file in; if this is empty, the current package context is selected

mkDirs - flag for creating the parent directories of the file

Throws:

NullPointerException - if output is null

IOException - if an I/O error occurs

Since:

1.0

resource

public static final Path resource(@GloopParameter(allowNull=false)
                                  String resource,
                                  String packageName)
                           throws IOException

Open a resource from the specified package context, returning a Path to read from the resource.

Parameters:

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

readContent

public static final Stream<String> readContent(@GloopParameter(allowNull=false)
                                               String resource,
                                               String packageName)
                                        throws IOException

Attempt to read a resource from the selected package context, returning a Stream object to read from the resource. This method does not read all lines, but instead populates lazily as the stream is consumed.

Parameters:

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

readContent

public static final void readContent(String packageName,
                                     String resource,
                                     Closure<String> closure)
                              throws IOException

Attempt to read a resource from the selected package context and executes the closure for every line of the resource content.

Parameters:

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

closure - the closure to execute

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

readAllContent

public static final String readAllContent(@GloopParameter(allowNull=false)
                                          String resource,
                                          String packageName)
                                   throws IOException

Attempt to read a resource from the selected package context, returning an String object to read from the resource.

Parameters:

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

resource - the name of the resource (e.g. conf/package.xml)

Throws:

IOException - if an I/O error occurs

io.toro.martini.ipackage.exception.PackageRuntimeException - if packageName is empty and current package context is not set properly

Since:

1.0

getTextFileInputCursor

@GloopObjectParameter("output{\n  output{\n    linesInputCursor[]\n  }\n}")
public static GloopModel getTextFileInputCursor(@GloopParameter(allowNull=false)
                                                InputStream flatFileData,
                                                @GloopParameter(defaultValue="UTF-8")
                                                String encoding,
                                                @GloopParameter(defaultValue="\n")
                                                String recordSeparator,
                                                GloopExecutionContext context)

Read an InputStream and return a Gloop cursor for reading from the resource.

Parameters:

flatFileData - resource InputStream

encoding - character encoding

recordSeparator - record delimiter

context - execution context

Returns:

cursor for the provided stream

Since:

1.0

readFileAsMultipart

@GloopObjectParameter("output{\n  multipartFile#io.toro.martini.http.MultipartFile{\n  }\n}")
public static GloopModel readFileAsMultipart(@GloopParameter(allowNull=false)
                                             String filePath,
                                             @GloopParameter(allowNull=false)
                                             String contentType)

Wrap a file path and return a multi-part GloopModel.

Parameters:

filePath - the file path

contentType - content type of file that conforms to HTTP specifications

Returns:

the multi-part GloopModel; null if it does not exist

Since:

1.0

See Also:

HTTP specification

readPackageFileAsMultipart

@GloopObjectParameter("output{\n  multipartFile#io.toro.martini.http.MultipartFile{\n  }\n}")
public static GloopModel readPackageFileAsMultipart(@GloopParameter(allowNull=false)
                                                    String resourceName,
                                                    String packageName,
                                                    @GloopParameter(allowNull=false)
                                                    String contentType)

Wrap a resource from a Martini package and return a multi-part GloopModel.

Parameters:

resourceName - the name of the resource (e.g. conf/package.xml)

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

contentType - content type of file that conforms HTTP specifications

Returns:

the multi-part GloopModel; null if the file does not exist

Since:

1.0

See Also:

HTTP specification

readLines

@GloopObjectParameter("output{\n  output{\n    linesInputCursor[]\n  }\n}")
public static GloopModel readLines(@GloopParameter(allowNull=false)
                                   String resource,
                                   String packageName,
                                   @GloopParameter(defaultValue="UTF-8")
                                   String encoding,
                                   @GloopParameter(defaultValue="\n")
                                   String lineSeparator,
                                   GloopExecutionContext context)
                            throws IOException

Read a resource file residing in a Martini package and return a Gloop cursor for said file.

Parameters:

resource - the name of the resource (e.g. conf/package.xml)

packageName - the name of the package to read the resource from; if this is empty, the current package context is selected

encoding - character encoding

lineSeparator - record delimiter

context - execution context

Returns:

the Gloop cursor

Throws:

IOException - if an I/O error occurs

Since:

1.0