• BlackBerry Dynamics
  • Runtime library for Android applications
  • 12.1.1.43
File Class Reference

Extension of java.io.File for working with the secure file system. More...

Inheritance diagram for File:
File

Description

This class is a subclass of java.io.File for working with the BlackBerry Dynamics secure file system.

See the com.good.gd.file package documentation for an introduction to the secure file system.

This class has the same programming interface as the java.io.File class with the following exceptions.

  • The deleteOnExit method has no effect. Note that deleteOnExit is not generally advisable on the native platform in any case.
  • The permission setting methods have no effect. This includes setReadOnly, setWritable, setReadable, and setExecutable. All files in the secure store are always readable, writable, and not executable.
  • There is no current working directory. Paths should always be specified as absolute paths, beginning with a / character.
  • Resolution of paths to canonical form isn't supported. The getCanonical... methods return the same values as the corresponding getAbsolute... methods.
  • The getTotalSpace method returns information relating to the device storage partition that holds the secure file system. All files and directories in the secure store will be in the same storage partition.

See also
java.io.File class reference on the android.com developer website for details of all methods.

Notice

The following notice applies to the original API on which this API is based, and to its documentation. The documentation of this API has been revised from the original.

/*
 * Copyright (C) 2006 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Public Member Functions

 File (String parent, String child)
 Construct new instance from String objects containing parent path and child path. More...
 
 File (java.io.File parent, String child)
 Construct new instance from parent File and child String. More...
 
 File (URI uri)
 Construct new instance from file: URI. More...
 
 File (String pathname)
 Construct new instance from String. More...
 
boolean canExecute ()
 Check execute permission; always returns false. More...
 
boolean canRead ()
 Check read permission. More...
 
boolean canWrite ()
 Check write permission. More...
 
boolean createNewFile () throws IOException
 Create an empty file in the secure file system. More...
 
boolean delete ()
 Delete a file or directory from the secure store. More...
 
void deleteOnExit ()
 Mark a file or directory to be deleted on exit (not supported). More...
 
int compareTo (java.io.File pathname)
 Lexicographic comparison of paths. More...
 
boolean equals (Object obj)
 Lexicographic comparison of path and other object. More...
 
boolean exists ()
 Test for the existence of a file or directory in the secure store. More...
 
java.io.File getAbsoluteFile ()
 Get the absolute form of a path in the secure file system. More...
 
String getAbsolutePath ()
 Get a String containing the absolute form of a path in the secure file system. More...
 
java.io.File getCanonicalFile () throws IOException
 Get the canonical form of a path in the secure file system (not supported). More...
 
String getCanonicalPath () throws IOException
 Get a String containing the canonical form of a path in the secure file system (not supported). More...
 
String getName ()
 Get the name part of a path in the secure file system. More...
 
String getParent ()
 Get the parent part of a path in the secure file system. More...
 
java.io.File getParentFile ()
 Get a new instance containing the parent part of this instance's path in the secure file system. More...
 
String getPath ()
 Convert the path to a String. More...
 
long getFreeSpace ()
 Check how much unallocated space there is on the storage partition that contains the secure store. More...
 
long getTotalSpace ()
 Check the size of the storage partition that contains the secure store. More...
 
long getUsableSpace ()
 Check how much space is available to use on the storage partition that contains the secure store. More...
 
int hashCode ()
 Compute a hash code for a path in the secure store. More...
 
boolean isAbsolute ()
 Test whether a path in the secure store is absolute. More...
 
boolean isDirectory ()
 Check for the existence of a directory in the secure store. More...
 
boolean isFile ()
 Check for the existence of a plain file in the secure store. More...
 
boolean isHidden ()
 Check if a file or directory in the secure store is hidden. More...
 
long lastModified ()
 Get the last modified time of a file or directory in the secure store. More...
 
long length ()
 Get the size of a file in the secure store, as if decrypted. More...
 
String[] list ()
 Contents of a secure file system directory as a String array. More...
 
String[] list (java.io.FilenameFilter filter)
 Filtered list of the contents of a secure file system directory as a String array. More...
 
java.io.File[] listFiles ()
 Contents of a secure file system directory as a File array. More...
 
java.io.File[] listFiles (java.io.FileFilter filter)
 Filtered list of the contents of a secure file system directory as a File array. More...
 
java.io.File[] listFiles (java.io.FilenameFilter filter)
 Filtered list of the contents of a secure file system directory as a File array. More...
 
boolean mkdir ()
 Create a sub-directory in the secure file system. More...
 
boolean mkdirs ()
 Create all directories on a path, in the secure file system. More...
 
boolean renameTo (java.io.File dest)
 Move or rename a file or directory within the secure file system. More...
 
boolean setExecutable (boolean executable)
 Set execute permission for owner (not supported). More...
 
boolean setExecutable (boolean executable, boolean ownerOnly)
 Set execute permission for owner or all (not supported). More...
 
boolean setReadable (boolean readable)
 Set read permission for owner (not supported). More...
 
boolean setReadable (boolean readable, boolean ownerOnly)
 Set read permission for owner or all (not supported). More...
 
boolean setWritable (boolean writable)
 Set write permission for owner (not supported). More...
 
boolean setWritable (boolean writable, boolean ownerOnly)
 Set write permission for owner or all (not supported). More...
 
boolean setLastModified (long time)
 Set the last modified time of a file or directory in the secure file system. More...
 
boolean setReadOnly ()
 Remove write permission (not supported). More...
 
String toString ()
 Convert the path to a String. More...
 
URI toURI ()
 Convert the path to a URI. More...
 

Static Public Member Functions

static java.io.File createTempFile (String prefix, String suffix) throws IOException
 Create a temporary file in the default directory for temporary files in the secure store. More...
 
static java.io.File createTempFile (String prefix, String suffix, java.io.File directory) throws IOException
 Create a temporary file in the specified directory in the secure store. More...
 
static java.io.File[] listRoots ()
 List the available roots in the secure file system; always returns ["/"]. More...
 

Constructor & Destructor Documentation

◆ File() [1/4]

File ( String  parent,
String  child 
)

Call this constructor to create a new instance from a parent path and a child path.

Parameters
parentString containing the parent path, within the secure file system.
childString containing the child path, which will be appended to the parent path.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ File() [2/4]

File ( java.io.File  parent,
String  child 
)

Call this constructor to create a new instance from a parent File and a child path.

Parameters
parentFile containing the parent path, within the secure file system.
childString containing the child path, which will be appended to the parent path.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ File() [3/4]

File ( URI  uri)

Call this constructor to create a new instance from a Uniform Resource Identifier (URI) with the file: scheme.

Parameters
uriURI containing the path, within the secure file system.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

◆ File() [4/4]

File ( String  pathname)

Call this constructor to create a new instance from a String.

Parameters
pathnameString containing the path, within the secure file system.
Exceptions
com.good.gd.error.GDNotAuthorizedErrorif BlackBerry Dynamics authorization processing has not yet completed.

Member Function Documentation

◆ canExecute()

boolean canExecute ( )

Call this method to test whether the file at the instance's path is executable. This method is provided for completeness; files in the secure store are never executable.

Returns
false always.

◆ canRead()

boolean canRead ( )

Call this method to test whether the file or directory at the instance's path is readable. Files and directories in the secure store are always readable, so this method only checks for existence.

Returns
true if the instance's path corresponds to a file or directory that exists in the secure store.
false otherwise.

◆ canWrite()

boolean canWrite ( )

Call this method to test whether the file or directory at the instance's path is writable. Files and directories in the secure store are always writable, so this method only checks for existence.

Returns
true if the instance's path corresponds to a file or directory that exists in the secure store.
false otherwise.

◆ createNewFile()

boolean createNewFile ( ) throws IOException

Call this method to create a new, empty file at the instance's path. If a file already exists at the path in the secure file system, calling this method has no effect.

Returns
true if the file did not exist and was created.
false otherwise.
Exceptions
IOException

◆ createTempFile() [1/2]

static java.io.File createTempFile ( String  prefix,
String  suffix 
) throws IOException
static

Calling this method is the same as calling the three-parameter method, below, with a null directory parameter.

Exceptions
IOException

◆ createTempFile() [2/2]

static java.io.File createTempFile ( String  prefix,
String  suffix,
java.io.File  directory 
) throws IOException
static

Call this method to create a temporary file in the specified directory in the secure store. A file name will be generated that begins with the specified prefix, ends with the specified suffix, and is unique in the directory.

Parameters
prefixString containing the file name prefix. Must be at least three characters.
suffixString containing the file name suffix. Defaults to ".tmp" if a null pointer is passed.
directoryFile containing the path of the directory in which the temporary file is to be created, within the secure store. Defaults to a system designated path if a null pointer is passed.
Returns
New File instance for the created temporary file.
Exceptions
IOException

◆ delete()

boolean delete ( )

Call this method to delete the file or directory at the instance's path.

Returns
true if the file or directory existed and was deleted.
false otherwise.

◆ deleteOnExit()

void deleteOnExit ( )

Call this method to request that the instance's file is to be deleted when the JVM terminates. The request will be ignored. Calling this method has no effect.

This method is provided for completeness only; the secure store doesn't support delete-on-exit.

◆ compareTo()

int compareTo ( java.io.File  pathname)

Call this method to compare the path of one instance with the path of another, lexicographically.

See also
compareTo method documentation in the java.io.File class reference on the android.com developer website for return values.

◆ equals()

boolean equals ( Object  obj)

Call this method to compare the instance's path with another object.

Parameters
objObject to which comparison is being made.
Returns
true if the instance's path matches the object.
false otherwise.

◆ exists()

boolean exists ( )

This method checks if the instance's path corresponds to an existing file or directory in the secure store.

Returns
true if the instance's path exists in the secure store.
false otherwise.

◆ getAbsoluteFile()

java.io.File getAbsoluteFile ( )

This method returns a new instance whose path is the absolute form of this instance's path.

Note that there is no current working directory in the secure file system. Paths that are not absolute will be interpreted relative to the root directory of the secure store.

Returns
File containing the absolute path.

◆ getAbsolutePath()

String getAbsolutePath ( )

This method returns the absolute form of the instance's path in a String.

Note that there is no current working directory in the secure file system. Paths that are not absolute will be interpreted relative to the root directory of the secure store.

Returns
String containing the absolute path.

◆ getCanonicalFile()

java.io.File getCanonicalFile ( ) throws IOException

This class doesn't support resolution of paths to canonical form.

Returns
the same value as getAbsoluteFile.

◆ getCanonicalPath()

String getCanonicalPath ( ) throws IOException

This class doesn't support resolution of paths to canonical form.

Returns
the same value as getAbsoluteFile.

◆ getName()

String getName ( )
Returns
String containing the name part of the instance's path.

◆ getParent()

String getParent ( )
Returns
String containing the parent part of the instance's path, or a null pointer if there is no parent part.

◆ getParentFile()

java.io.File getParentFile ( )
Returns
File containing the parent part of the instance's path, or a null pointer if there is no parent part.

◆ getPath()

String getPath ( )
Returns
String containing the instance's path in the secure store.

◆ getFreeSpace()

long getFreeSpace ( )

This method returns the amount of unallocated space in the storage partition that contains the secure store, as a number of bytes.

Returns
long representation of the number of unallocated bytes.

◆ getTotalSpace()

long getTotalSpace ( )

This method returns the size of the partition that contains the secure store, in bytes.

Returns
long representation of the size of the partition in bytes.

◆ getUsableSpace()

long getUsableSpace ( )

This method returns the amount of useable space in the partition that contains the secure store, as a number of bytes.

Returns
long representation of the number of useable bytes.

◆ hashCode()

int hashCode ( )

This method computes a hash code for the instance's path.

Returns
int representation of the computed hash code.

◆ isAbsolute()

boolean isAbsolute ( )
Returns
true if the instance's path is in absolute form.
false otherwise.

◆ isDirectory()

boolean isDirectory ( )

This method checks if the instance's path corresponds to an existing directory in the secure store.

Returns
true if the instance's path exists in the secure store, and is a directory.
false otherwise.

◆ isFile()

boolean isFile ( )

Call this method to check if the instance's path corresponds to a plain file, not a directory, in the secure store.

Returns
true if the instance's path exists in the secure store, and is a plain file.
false otherwise.

◆ isHidden()

boolean isHidden ( )
Returns
true if the instance's path is a hidden file or directory.
false otherwise.

◆ lastModified()

long lastModified ( )
Returns
long representation of the modified time of the instance's file or directory.

◆ length()

long length ( )

Call this method to obtain the length of the instance's file in the secure store. Note that the value is based on file as if it had been decrypted.

Returns
long representation of the length of the file in bytes.

◆ list() [1/2]

String [] list ( )

This method returns a list of the decrypted file and directory names that are in the instance's directory, in a String array.

Returns
String array of the names of the files and directories.

◆ list() [2/2]

String [] list ( java.io.FilenameFilter  filter)

This method returns a list of the decrypted file and directory names that are in the instance's directory, and which satisfy the specified filter criteria, in a String array.

Parameters
filterjava.io.FilenameFilter representation of the filter criteria.
Returns
String array of the names of the files and directories.

◆ listFiles() [1/3]

java.io.File [] listFiles ( )

This method returns a list of the decrypted file and directory names that are in the instance's directory, in a File array. The array elements returned are always instances of com.good.gd.file.File, and can be safely cast to that type.

Returns
File array of the names of the files and directories.

◆ listFiles() [2/3]

java.io.File [] listFiles ( java.io.FileFilter  filter)

This method returns a list of the decrypted file and directory names that are in the instance's directory, and which satisfy the specified filter criteria, in a File array. The array elements returned are always instances of com.good.gd.file.File, and can be safely cast to that type.

Parameters
filterjava.io.FileFilter representation of the filter criteria.
Returns
File array of the names of the files and directories.

◆ listFiles() [3/3]

java.io.File [] listFiles ( java.io.FilenameFilter  filter)

This method returns a list of the decrypted file and directory names that are in the instance's directory, and which satisfy the specified filter criteria, in a File array. The array elements returned are always instances of com.good.gd.file.File, and can be safely cast to that type.

Parameters
filterjava.io.FilenameFilter representation of the filter criteria.
Returns
File array of the names of the files and directories.

◆ listRoots()

static java.io.File [] listRoots ( )
static

This method returns a list of the available roots in the secure file system. There is only one root in the secure file system, so this method always returns an array with a single element, "/".

Returns
File array of available roots in the secure file system.

◆ mkdir()

boolean mkdir ( )

Call this method to create a directory at the instance's path, within the secure file system. The parent directory must already exist.

If there is already a file or directory at the instance's path, then this method will fail.

Returns
true if the directory was created.
false otherwise.

◆ mkdirs()

boolean mkdirs ( )

Call this method to create a directory at the instance's path, within the secure file system. Any missing directories on the instance's path will also be created.

If there is already a file or directory at the instance's path, then this method will fail.

Returns
true if the directory was created.
false otherwise.

◆ renameTo()

boolean renameTo ( java.io.File  dest)
Parameters
destFile representation of the destination path, within the secure file system.
Returns
true if the instance's file or directory was moved or renamed to the specified destination.
false otherwise.

◆ setExecutable() [1/2]

boolean setExecutable ( boolean  executable)

Call this method to set or clear owner execute permission on the file at the instance's path. This method is provided for completeness; files in the secure store are never executable.

Returns
true if the path exists and the specified permission is false.
false otherwise.

◆ setExecutable() [2/2]

boolean setExecutable ( boolean  executable,
boolean  ownerOnly 
)

Call this method to set or clear execute permission on the file at the instance's path. This method is provided for completeness; files in the secure store are never executable.

Returns
true if the path exists and the specified permission is false.
false otherwise.

◆ setReadable() [1/2]

boolean setReadable ( boolean  readable)

Call this method to set or clear owner read permission on the file at the instance's path. This method is provided for completeness; files in the secure store are always readable.

Returns
true if the path exists and the specified permission is true.
false otherwise.

◆ setReadable() [2/2]

boolean setReadable ( boolean  readable,
boolean  ownerOnly 
)

Call this method to set or clear read permission on the file at the instance's path. This method is provided for completeness; files in the secure store are always readable.

Returns
true if the path exists and the specified permission is true.
false otherwise.

◆ setWritable() [1/2]

boolean setWritable ( boolean  writable)

Call this method to set or clear owner write permission on the file at the instance's path. This method is provided for completeness; files in the secure store are always writable.

Returns
true if the path exists and the specified permission is true.
false otherwise.

◆ setWritable() [2/2]

boolean setWritable ( boolean  writable,
boolean  ownerOnly 
)

Call this method to set or clear write permission on the file at the instance's path. This method is provided for completeness; files in the secure store are always writable.

Returns
true if the path exists and the specified permission is true.
false otherwise.

◆ setLastModified()

boolean setLastModified ( long  time)

Call this method to set the last modified time of the instance's file or directory in the secure file system.

Parameters
timelong representation of the time to set.
Returns
true if the last modified time was set.
false otherwise.

◆ setReadOnly()

boolean setReadOnly ( )

Call this method to clear write permission on the file at the instance's path. This method is provided for completeness; files in the secure store are always writable.

Returns
false always.

◆ toString()

String toString ( )

This method returns the same value as the getPath method.

Returns
String containing the instance's path in the secure store.

◆ toURI()

URI toURI ( )

The method returns a Uniform Resource Identifier (URI) for the path in the secure file system. The URI will have the file: scheme.

Note that the URI isn't transferable and can only be used within the BlackBerry Dynamics programming interface.

Returns
URI containing the path in the secure store.