Location (Apache Twill 0.14.0-SNAPSHOT API)

```
public interface Location
```
This interface defines the location and operations of a resource on the filesystem.
Location is agnostic to the type of file system the resource is on.

Field Summary

Fields
Modifier and Type Field and Description

static String TEMP_FILE_SUFFIX
Suffix added to every temp file name generated with getTempFile(String).

Fields
Modifier and Type	Field and Description
`static String`	`TEMP_FILE_SUFFIX` Suffix added to every temp file name generated with `getTempFile(String)`.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Location`	`append(String child)` Appends the child to the current `Location`.
`boolean`	`createNew()` Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
`boolean`	`createNew(String permission)` Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
`boolean`	`delete()` Deletes the file or directory denoted by this abstract pathname.
`boolean`	`delete(boolean recursive)` Deletes the file or directory denoted by this abstract pathname.
`boolean`	`exists()` Checks if the this location exists.
`String`	`getGroup()` Returns the group of the location.
`InputStream`	`getInputStream()`
`LocationFactory`	`getLocationFactory()` Returns the location factory used to create this instance.
`String`	`getName()`
`OutputStream`	`getOutputStream()`
`OutputStream`	`getOutputStream(String permission)` Creates an `OutputStream` for this location with the given permission.
`String`	`getOwner()` Returns the owner of the location.
`String`	`getPermissions()` Returns the permissions of this `Location`.
`Location`	`getTempFile(String suffix)` Returns unique location for temporary file to be placed near this location.
`boolean`	`isDirectory()` Checks if this location represents a directory.
`long`	`lastModified()`
`long`	`length()`
`List<Location>`	`list()` List the locations under this location.
`boolean`	`mkdirs()` Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories.
`boolean`	`mkdirs(String permission)` Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories.
`Location`	`renameTo(Location destination)` Moves the file or directory denoted by this abstract pathname.
`void`	`setGroup(String group)` Sets the group of the location.
`void`	`setPermissions(String permission)` Sets the permissions on this location.
`URI`	`toURI()`

- Field Detail
  - TEMP_FILE_SUFFIX
```
static final String TEMP_FILE_SUFFIX
```
    Suffix added to every temp file name generated with getTempFile(String).
    
    See Also:
    
    Constant Field Values
- Method Detail
  - exists
```
boolean exists()
        throws IOException
```
    Checks if the this location exists.
    
    Returns:
    
    true if found; false otherwise.
    
    Throws:
    
    IOException
  - getName
```
String getName()
```
    Returns:
    
    Returns the name of the file or directory denoteed by this abstract pathname.
  - createNew
```
boolean createNew()
           throws IOException
```
    Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
    
    Returns:
    
    true if the file is successfully create, false otherwise.
    
    Throws:
    
    IOException - if error encountered during creation of the file
  - createNew
```
boolean createNew(String permission)
           throws IOException
```
    Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist. The newly created file will have permission set based on the given permission settings.
    
    Parameters:
    
    permission - A permission string. It has to be either a three digit or a nine character string. For the three digit string, it is similar to the UNIX permission numeric representation. The first digit is the permission for owner, second digit is the permission for group and the third digit is the permission for all. For the nine character string, it uses the format as specified by the PosixFilePermissions.fromString(String) method.
    
    Returns:
    
    true if the file is successfully create, false otherwise.
    
    Throws:
    
    IOException - if error encountered during creation of the file
  - getPermissions
```
String getPermissions()
               throws IOException
```
    Returns the permissions of this Location. The permission string is a nine character string as the format specified by the PosixFilePermissions.fromString(String) method.
    
    Throws:
    
    IOException - if failed to get the permissions of the location
    
    UnsupportedOperationException - if Posix file permissions are not supported by the local file system
  - getOwner
```
String getOwner()
         throws IOException
```
    Returns the owner of the location.
    
    Throws:
    
    IOException - if failed to get the owner of the location
  - getGroup
```
String getGroup()
         throws IOException
```
    Returns the group of the location.
    
    Throws:
    
    IOException - if failed to get the group of the location
    
    UnsupportedOperationException - if Posix style groups are not supported by the local file system
  - setGroup
```
void setGroup(String group)
       throws IOException
```
    Sets the group of the location.
    
    Throws:
    
    IOException - if failed to set the group of the location
    
    UnsupportedOperationException - if Posix style groups are not supported by the local file system
  - setPermissions
```
void setPermissions(String permission)
             throws IOException
```
    Sets the permissions on this location.
    
    Parameters:
    
    permission - A permission string. See createNew(String) for the format.
    
    Throws:
    
    IOException - if failed to set the permission
    
    UnsupportedOperationException - if Posix file permissions are not supported by the local file system
  - getInputStream
```
InputStream getInputStream()
                    throws IOException
```
    Returns:
    
    An InputStream for this location.
    
    Throws:
    
    IOException
  - getOutputStream
```
OutputStream getOutputStream()
                      throws IOException
```
    Returns:
    
    An OutputStream for this location.
    
    Throws:
    
    IOException
  - getOutputStream
```
OutputStream getOutputStream(String permission)
                      throws IOException
```
    Creates an OutputStream for this location with the given permission. The actual permission supported depends on implementation.
    
    Parameters:
    
    permission - A permission string. It has to be either a three digit or a nine character string. For the three digit string, it is similar to the UNIX permission numeric representation. The first digit is the permission for owner, second digit is the permission for group and the third digit is the permission for all. For the nine character string, it uses the format as specified by the PosixFilePermissions.fromString(String) method.
    
    Returns:
    
    An OutputStream for writing to this location.
    
    Throws:
    
    IOException - If failed to create the OutputStream.
  - append
```
Location append(String child)
         throws IOException
```
    Appends the child to the current Location.
    Returns a new instance of Location.
    
    Parameters:
    
    child - to be appended to this location.
    
    Returns:
    
    A new instance of Location
    
    Throws:
    
    IOException
  - getTempFile
```
Location getTempFile(String suffix)
              throws IOException
```
    Returns unique location for temporary file to be placed near this location. Allows all temp files to follow same pattern for easier management of them.
    
    Parameters:
    
    suffix - part of the file name to include in the temp file name
    
    Returns:
    
    location of the temp file
    
    Throws:
    
    IOException
  - toURI
```
URI toURI()
```
    Returns:
    
    A URI for this location.
  - delete
```
boolean delete()
        throws IOException
```
    Deletes the file or directory denoted by this abstract pathname. If this pathname denotes a directory, then the directory must be empty in order to be deleted.
    
    Returns:
    
    true if and only if the file or directory is successfully deleted; false otherwise.
    
    Throws:
    
    IOException
  - delete
```
boolean delete(boolean recursive)
        throws IOException
```
    Deletes the file or directory denoted by this abstract pathname. If this pathname denotes a directory and recursive is true, then content of the directory will be deleted recursively, otherwise the directory must be empty in order to be deleted. Note that when calling this method with recursive = true for a directory, any failure during deletion will have some entries inside the directory being deleted while some are not.
    
    Parameters:
    
    recursive - Indicate if recursively delete a directory. Ignored if the pathname represents a file.
    
    Returns:
    
    true if and only if the file or directory is successfully deleted; false otherwise.
    
    Throws:
    
    IOException
  - renameTo
```
@Nullable
Location renameTo(Location destination)
                     throws IOException
```
    Moves the file or directory denoted by this abstract pathname.
    
    Parameters:
    
    destination - destination location
    
    Returns:
    
    new location if and only if the file or directory is successfully moved; null otherwise.
    
    Throws:
    
    IOException
  - mkdirs
```
boolean mkdirs()
        throws IOException
```
    Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories.
    
    Returns:
    
    true if and only if the directory was created; false otherwise
    
    Throws:
    
    IOException
  - mkdirs
```
boolean mkdirs(String permission)
        throws IOException
```
    Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories. The directories will be created with the exact given permissions, regardless of a possible umask setting.
    
    Parameters:
    
    permission - A permission string. It has to be either a three digit or a nine character string. For the three digit string, it is similar to the UNIX permission numeric representation. The first digit is the permission for owner, second digit is the permission for group and the third digit is the permission for all. For the nine character string, it uses the format as specified by the PosixFilePermissions.fromString(String) method.
    
    Returns:
    
    true if and only if the directory was created; false otherwise
    
    Throws:
    
    IOException
  - length
```
long length()
     throws IOException
```
    Returns:
    
    Length of file.
    
    Throws:
    
    IOException
  - lastModified
```
long lastModified()
           throws IOException
```
    Returns:
    
    Last modified time of file.
    
    Throws:
    
    IOException
  - isDirectory
```
boolean isDirectory()
             throws IOException
```
    Checks if this location represents a directory.
    
    Returns:
    
    true if it is a directory, false otherwise.
    
    Throws:
    
    IOException
  - list
```
List<Location> list()
             throws IOException
```
    List the locations under this location.
    
    Returns:
    
    Immutable List of locations under this location. An empty list is returned if this location is not a directory.
    
    Throws:
    
    IOException
  - getLocationFactory
```
LocationFactory getLocationFactory()
```
    Returns the location factory used to create this instance.
    
    Returns:
    
    The LocationFactory instance for creating this instance.

Interface Location

Field Summary

Method Summary

Field Detail

TEMP_FILE_SUFFIX

Method Detail

exists

getName

createNew

createNew

getPermissions

getOwner

getGroup

setGroup

setPermissions

getInputStream

getOutputStream

getOutputStream

append

getTempFile

toURI

delete

delete

renameTo

mkdirs

mkdirs

length

lastModified

isDirectory

list

getLocationFactory