FileServices

java.lang.Object
- com.ansca.corona.ApplicationContextProvider
- - com.ansca.corona.storage.FileServices

```
public class FileServices
extends ApplicationContextProvider
```
Provides easy seamless access to files that are external to the application, files within the APK's "assets" directory, and files within Google Play expansion files. Also provides simple methods for copying, moving, and opening these files as well as fetching their extensions and mime types.
If the application uses Google Play expansion files, then this class will attempt to fetch asset files within these expansion files first before looking for them within the APK's "assets" directory. By default, this class assumes that these expansion files are named after the application's package name and version code. If they use a different name (such as a different version code), then you can change it by calling this class' setMainExpansionFileName() and setPatchExpansionFileName() methods. If this application uses Corona's built-in Google Licensing feature, then Corona will set these file names automatically according to the names provided by the Google Licensing server.
All methods in this class are thread safe and can be called from any thread.

Constructor Summary

Constructors
Constructor and Description
`FileServices(android.content.Context context)` Creates an object that provides easy access to the file system and this application's internal files in the APK's asset files and Google Play expansion files.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`copyFile(File sourceFile, File destinationFile)` Copies the given file to the given destination safely without exceptions.
`boolean`	`copyFile(String sourceFilePath, String destinationFilePath)` Copies the given file to the given destination safely without exceptions.
`boolean`	`doesAssetFileExist(String filePath)` Determines if the given file exists in the application's assets directory or in its expansion files.
`boolean`	`doesResourceFileExist(String filePath)` Determines if the given file exists in the application's resource directory
`File`	`extractAssetFile(File assetFile)` Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files.
`File`	`extractAssetFile(File assetFile, boolean overwrite)` Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files.
`File`	`extractAssetFile(String filePath)` Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files.
`File`	`extractAssetFile(String filePath, boolean overwrite)` Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files.
`AssetFileLocationInfo`	`getAssetFileLocation(String filePath)` Determines where the given asset file can be found.
`byte[]`	`getBytesFromFile(File file)` Fetches all bytes from the given file.
`byte[]`	`getBytesFromFile(String filePath)` Fetches all bytes from the given file.
`File`	`getExpansionFileDirectory()` Gets the directory where this application's "main" and "patch" expansion files are supposed to reside in.
`String`	`getExtensionFrom(File file)` Extracts the extension from the given file.
`String`	`getExtensionFrom(String fileName)` Extracts the extension from the given file name.
`File`	`getMainExpansionFile()` Gets the path and file name of this application's "main" expansion file.
`String`	`getMimeTypeFrom(android.net.Uri uri)` Handles requests for the MIME type of the data at the given URI.
`File`	`getPatchExpansionFile()` Gets the path and file name of this application's "patch" expansion file.
`boolean`	`isAssetFile(String filePath)` Determines if the given path\file name is an asset file inside of the APK or expansion file.
`void`	`loadExpansionFiles()` Loads this application's expansion files for fast access.
`boolean`	`moveFile(File sourceFile, File destinationFile)` Moves the given file to the given destination safely without exceptions.
`android.content.res.AssetFileDescriptor`	`openAssetFileDescriptorFor(File file)` Safely opens a file via an AssetFileDescriptor without exceptions.
`android.content.res.AssetFileDescriptor`	`openAssetFileDescriptorFor(String filePath)` Safely opens a file via an AssetFileDescriptor without exceptions.
`InputStream`	`openFile(File file)` Safely opens an input stream to the given file without exceptions.
`InputStream`	`openFile(String filePath)` Safely opens an input stream to the given file without exceptions.
`void`	`setMainExpansionFileName(String fileName)` Sets the name of the "main" expansion file to be loaded.
`void`	`setPatchExpansionFileName(String fileName)` Sets the name of the "patch" expansion file to be loaded.
`boolean`	`writeToFile(InputStream inputStream, File destinationFile)` Writes the given input stream's bytes to the destination file safely without exceptions.

Methods inherited from class com.ansca.corona.ApplicationContextProvider
getApplicationContext

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FileServices
```
public FileServices(android.content.Context context)
```
    Creates an object that provides easy access to the file system and this application's internal files in the APK's asset files and Google Play expansion files.
    
    Parameters:
    context - Reference to an Android created context used to access the system's directories.
    Setting this to null will cause an exception to be thrown.
- Method Detail
  - isAssetFile
```
public boolean isAssetFile(String filePath)
```
    Determines if the given path\file name is an asset file inside of the APK or expansion file.
    
    Parameters:
    fileName - The path and file name to check if it is an asset file. Cannot be null or empty.
    
    Returns:
    Returns true if the given file is inside of the APK or expansion file.
    Returns false if the given file is an external file, null, or an empty string.
  - doesAssetFileExist
```
public boolean doesAssetFileExist(String filePath)
```
    Determines if the given file exists in the application's assets directory or in its expansion files.
    
    Parameters:
    filePath - Relative path to the asset file.
    
    Returns:
    Returns true if the file exists in this application's assets directory or in its expansions files.
    Returns false if the file could not be found.
  - doesResourceFileExist
```
public boolean doesResourceFileExist(String filePath)
```
    Determines if the given file exists in the application's resource directory
    
    Parameters:
    filePath - Relative path to the resource file (e.g. "drawable/image.png").
    
    Returns:
    Returns true if the file exists in this application's resource directory
    Returns false if the file could not be found.
  - getAssetFileLocation
```
public AssetFileLocationInfo getAssetFileLocation(String filePath)
```
    Determines where the given asset file can be found.
    Note that assets files are packaged within an APK file or within a Google Play expansion file. This method determines which package file contains the given asset, where the asset's bytes can be found within the package file, determines the asset's zip entry name if applicable, and whether or not the asset is compressed.
    This information can be used to directly read the asset's bytes for fast access, provided that the asset is not compressed. This is particularly usefull if the asset needs to be accessed from native C/C++ code or from a 3rd party library that does not support Android's AssetManager class.
    
    Parameters:
    filePath - Relative path to the assset file.
    
    Returns:
    Returns information about where the given asset is located.
    Returns null if the asset could not be found or if given an invalid argument.
  - getExpansionFileDirectory
```
public File getExpansionFileDirectory()
```
    Gets the directory where this application's "main" and "patch" expansion files are supposed to reside in.
    
    Returns:
    Returns the expansion file directory as a File object.
    Returns null if the expansion directory could not be found.
  - setMainExpansionFileName
```
public void setMainExpansionFileName(String fileName)
```
    Sets the name of the "main" expansion file to be loaded.
    This method is expected to be called if Google Licensing returns an expansion file name. Otherwise, the system will assume the expansion file name matches this application's package name and version code.
    
    Parameters:
    fileName - The name of the "main" expansion file, including the extension, but excluding the path.
    For example: "main.1.my.package.name.obb"
    Set to null or empty string to use the default expansion file name using this application's package name and version code.
  - getMainExpansionFile
```
public File getMainExpansionFile()
```
    Gets the path and file name of this application's "main" expansion file.
    
    Returns:
    Returns the expansion file's path and name as a File object.
    Returns null if the expansion directory could not be found.
  - setPatchExpansionFileName
```
public void setPatchExpansionFileName(String fileName)
```
    Sets the name of the "patch" expansion file to be loaded.
    This method is expected to be called if Google Licensing returns an expansion file name. Otherwise, the system will assume the expansion file name matches this application's package name and version code.
    
    Parameters:
    fileName - The name of the "patch" expansion file, including the extension, but excluding the path.
    For example: "patch.1.my.package.name.obb"
    Set to null or empty string to use the default expansion file name using this application's package name and version code.
  - getPatchExpansionFile
```
public File getPatchExpansionFile()
```
    Gets the path and file name of this application's "patch" expansion file.
    
    Returns:
    Returns the expansion file's path and name as a File object.
    Returns null if the expansion directory could not be found.
  - loadExpansionFiles
```
public void loadExpansionFiles()
```
    Loads this application's expansion files for fast access.
    Calling this method twice will cause it to close access to the last loaded expansion files and then reload the current expansion files. This method is called by the CoronaActivity's onCreate() method in case the existing expansion files were replaced while the application process was running in the background, which typically happens during testing.
  - openFile
```
public InputStream openFile(String filePath)
```
    Safely opens an input stream to the given file without exceptions.
    
    Parameters:
    filePath - The path and name of the file to be opened.
    
    Returns:
    Returns an input stream to the given file.
    Returns null if unable to find or access the given file.
  - openFile
```
public InputStream openFile(File file)
```
    Safely opens an input stream to the given file without exceptions.
    
    Parameters:
    filePath - The file to be opened.
    
    Returns:
    Returns an input stream to the given file.
    Returns null if unable to find or access the given file.
  - openAssetFileDescriptorFor
```
public android.content.res.AssetFileDescriptor openAssetFileDescriptorFor(String filePath)
```
    Safely opens a file via an AssetFileDescriptor without exceptions.
    
    Parameters:
    filePath - The path and name of the file to access.
    
    Returns:
    Returns an AssetFileDescriptor to the given file.
    Returns null if the file could not be found.
  - openAssetFileDescriptorFor
```
public android.content.res.AssetFileDescriptor openAssetFileDescriptorFor(File file)
```
    Safely opens a file via an AssetFileDescriptor without exceptions.
    
    Parameters:
    file - The file to access.
    
    Returns:
    Returns an AssetFileDescriptor to the given file.
    Returns null if the file could not be found.
  - extractAssetFile
```
public File extractAssetFile(String filePath)
```
    Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files. The file will be extracted to a hidden folder under the application's directory.
    If the given file has already been extracted, then this method will not attempt to extract it again unless this application has been re-installed on the device. For the re-installed case, Corona must assume that this application might have modified assets that need to be re-extracted.
    
    Parameters:
    filePath - Relative path to the asset file within the APK's assets directory or expansion files.
    
    Returns:
    Returns an absolute path to where the asset file was copied to.
    Returns null if unable to find the given asset file.
  - extractAssetFile
```
public File extractAssetFile(String filePath,
                    boolean overwrite)
```
    Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files. The file will be extracted to a hidden folder under the application's directory.
    If the given file has already been extracted, you can tell force the rewrite
    
    Parameters:
    filePath - Relative path to the asset file within the APK's assets directory or expansion files.
    overwrite - Whether the file should be overwrite whats already extracted, if anything. True to overwrite.
    
    Returns:
    Returns an absolute path to where the asset file was copied to.
    Returns null if unable to find the given asset file.
  - extractAssetFile
```
public File extractAssetFile(File assetFile)
```
    Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files. The file will be extracted to a hidden folder under the application's directory.
    If the given file has already been extracted, then this method will not attempt to extract it again unless this application has been re-installed on the device. For the re-installed case, Corona must assume that this application might have modified assets that need to be re-extracted.
    
    Parameters:
    assetFile - The asset file within the APK's assets directory or expansion files.
    
    Returns:
    Returns an absolute path to where the asset file was copied to.
    Returns null if unable to find the given asset file.
  - extractAssetFile
```
public File extractAssetFile(File assetFile,
                    boolean overwrite)
```
    Extracts the given asset file to an external directory to make it available to native C/C++ APIs that do not have access to this application's assets directory within the APK or its expansion files. The file will be extracted to a hidden folder under the application's directory.
    If the given file has already been extracted, then this method WILL attempt to extract it again
    
    Parameters:
    assetFile - The asset file within the APK's assets directory or expansion files.
    overwrite - Whether the file should be overwrite whats already extracted, if anything. True to overwrite.
    
    Returns:
    Returns an absolute path to where the asset file was copied to.
    Returns null if unable to find the given asset file.
  - getExtensionFrom
```
public String getExtensionFrom(File file)
```
    Extracts the extension from the given file.
    
    Parameters:
    file - The file to extract the extension from.
    
    Returns:
    Returns the extension from the given file name, excluding the '.' separator.
    Returns an empty string if the given file name does not have an extension.
    Returns null if the given argument was null.
  - getExtensionFrom
```
public String getExtensionFrom(String fileName)
```
    Extracts the extension from the given file name.
    
    Parameters:
    fileName - The path and name of the file to extract the extension from.
    
    Returns:
    Returns the extension from the given file name, excluding the '.' separator.
    Returns an empty string if the given file name does not have an extension.
    Returns null if the given argument was null or an empty string.
  - copyFile
```
public boolean copyFile(String sourceFilePath,
               String destinationFilePath)
```
    Copies the given file to the given destination safely without exceptions. Will overwrite the destination file if it already exists.
    
    Parameters:
    sourceFilePath - The path and file name to be copied. Cannot be null.
    destinationFilePath - The path and file name to copy the source file to. Cannot be null.
    
    Returns:
    Returns true if the file copy operation was successful. Returns false if not.
  - copyFile
```
public boolean copyFile(File sourceFile,
               File destinationFile)
```
    Copies the given file to the given destination safely without exceptions.
    Will overwrite the destination file if it already exists.
    Will create the destination's directories if it does not already exist.
    
    Parameters:
    sourceFile - The file to be copied. Cannot be null.
    destinationFile - The path and file name to copy the source file to. Cannot be null.
    
    Returns:
    Returns true if the file copy operation was successful. Returns false if not.
  - writeToFile
```
public boolean writeToFile(InputStream inputStream,
                  File destinationFile)
```
    Writes the given input stream's bytes to the destination file safely without exceptions.
    Will overwrite the destination file if it already exists.
    Will create the destination's directories if it does not already exist.
    
    Parameters:
    inputStream - The input stream to copy bytes from. Cannot be null.
    destinationFile - The path and file name to copy the input stream's bytes to. Cannot be null.
    
    Returns:
    Returns true if the file write operation was successful. Returns false if not.
  - moveFile
```
public boolean moveFile(File sourceFile,
               File destinationFile)
```
    Moves the given file to the given destination safely without exceptions.
    Will overwrite the destination file if it already exists.
    Will create the destination's directories if it does not already exist.
    
    Parameters:
    sourceFile - The file to be moved. Cannot be null.
    destinationFile - The path and file name to move the file to. Cannot be null. Does not have to have the same file name as the source.
    
    Returns:
    Returns true if the file was moved successful. Returns false if not.
  - getBytesFromFile
```
public byte[] getBytesFromFile(String filePath)
```
    Fetches all bytes from the given file.
    
    Parameters:
    filePath - The path and name of the file to read from.
    Relative paths are assumed to be asset files.
    
    Returns:
    Returns all of the bytes from the given file as a byte array.
    Returns null if the file was not found or if the application does not have read permission.
  - getBytesFromFile
```
public byte[] getBytesFromFile(File file)
```
    Fetches all bytes from the given file.
    
    Parameters:
    file - The file to read from.
    If the file has a relative path, then it is assumed to be an asset file.
    
    Returns:
    Returns all of the bytes from the given file as a byte array.
    Returns null if the file was not found or if the application does not have read permission.
  - getMimeTypeFrom
```
public String getMimeTypeFrom(android.net.Uri uri)
```
    Handles requests for the MIME type of the data at the given URI. Not supported by this class. Calling this method will cause an exception to be thrown.
    
    Parameters:
    uri - The URI to query.
    
    Returns:
    Returns a MIME type string for the given URI. Returns null if of an unknown type.

Class FileServices

Constructor Summary

Method Summary

Methods inherited from class com.ansca.corona.ApplicationContextProvider

Methods inherited from class java.lang.Object

Constructor Detail

FileServices

Method Detail

isAssetFile

doesAssetFileExist

doesResourceFileExist

getAssetFileLocation

getExpansionFileDirectory

setMainExpansionFileName

getMainExpansionFile

setPatchExpansionFileName

getPatchExpansionFile

loadExpansionFiles

openFile

openFile

openAssetFileDescriptorFor

openAssetFileDescriptorFor

extractAssetFile

extractAssetFile

extractAssetFile

extractAssetFile

getExtensionFrom

getExtensionFrom

copyFile

copyFile

writeToFile

moveFile

getBytesFromFile

getBytesFromFile

getMimeTypeFrom