com.google.appengine.api.files
Interface FileService

public interface FileService

This is the interface for interacting with the Google App Engine File Service. A FileService instance is obtained via FileServiceFactory.getFileService(). Currently there are two file systems supported: BLOBSTORE and GS When writing files in GS (Google Storage), you have to first create a writable file handle by using createNewGSFile, append to it and when all done writing, you must finalize the file for it to persist. Typical usage to create a new file in Google Storage is as follows:

   FileService fileService = FileServiceFactory.getFileService();
    GSFileOptionsBuilder optionsBuilder = new GSFileOptionsBuilder()
        .setBucket("mybucket")
        .setKey("myfile")
        .setMimeType("text/html")
        .setAcl("public_read")
        .addUserMetadata("myfield1", "my field value");
    AppEngineFile writableFile =
        fileService.createNewGSFile(optionsBuilder.build());
    // Open a channel to write to it
    boolean lock = false;
    FileWriteChannel writeChannel =
        fileService.openWriteChannel(writableFile, lock);
    // Different standard Java ways of writing to the channel
    // are possible. Here we use a PrintWriter:
    PrintWriter out = new PrintWriter(Channels.newWriter(writeChannel, "UTF8"));
    out.println("The woods are lovely dark and deep.");
    out.println("But I have promises to keep.");
    
    // Close without finalizing and save the file path for writing later
    out.close();
    String path = writableFile.getFullPath();
    
    // Write more to the file in a separate request:
    writableFile = new AppEngineFile(path);
    
    // This time lock because we intend to finalize
    lock = true;
    writeChannel = fileService.openWriteChannel(writableFile, lock);
    
    // This time we write to the channel using standard Java
    writeChannel.write(ByteBuffer.wrap(
        "And miles to go before I sleep.".getBytes()));
    
    // Now finalize
    writeChannel.closeFinally();
    // At this point the file is visible in App Engine as:
    // "/gs/mybucket/myfile" 
    // and to anybody on the Internet through Google Storage as:
    // (http://commondatastorage.googleapis.com/mybucket/myfile) 
    // So reading it through Files API:
    String filename = "/gs/mybucket/myfile";
    AppEngineFile readableFile = new AppEngineFile(filename);
    FileReadChannel readChannel =
        fileService.openReadChannel(readableFile, false);
    // Again, different standard Java ways of reading from the channel.
    BufferedReader reader =
        new BufferedReader(Channels.newReader(readChannel, "UTF8"));
    String line = reader.readLine();
    // line = "The woods are lovely dark and deep."
    readChannel.close();

Method Summary

AppEngineFile	createNewBlobFile(java.lang.String mimeType) Creates a new empty file in the BlobStore of the specified mime-type and returns an AppEngineFile representing the file.
AppEngineFile	createNewBlobFile(java.lang.String mimeType, java.lang.String blobInfoUploadedFileName) Creates a new empty file in the BlobStore of the specified mime-type and returns an AppEngineFile representing the file.
AppEngineFile	createNewGSFile(GSFileOptions fileOptions) Creates a new writable file in Google Storage of the specified mime-type and returns an AppEngineFile representing the file.
AppEngineFile	getBlobFile(BlobKey blobKey) Given a BlobKey returns the corresponding AppEngineFile.
BlobKey	getBlobKey(AppEngineFile file) Given a BLOBSTORE file that has been finalized, returns the BlobKey for the corresponding blob.
FileReadChannel	openReadChannel(AppEngineFile file, boolean lock) Given an AppEngineFile, returns a FileReadChannel that may be used for reading bytes from the file.
RecordReadChannel	openRecordReadChannel(AppEngineFile file, boolean lock) Given an AppEngineFile, returns a RecordReadChannel that may be used for reading records from a file written using the leveldb log format.
RecordWriteChannel	openRecordWriteChannel(AppEngineFile file, boolean lock) Given an AppEngineFile returns a RecordWriteChannel that may be used for writing to the file using the leveldb log format.
FileWriteChannel	openWriteChannel(AppEngineFile file, boolean lock) Given an AppEngineFile, returns a FileWriteChannel that may be used for appending bytes to the file.

Method Detail

createNewBlobFile

AppEngineFile createNewBlobFile(java.lang.String mimeType)
                                throws java.io.IOException

Creates a new empty file in the BlobStore of the specified mime-type and returns an AppEngineFile representing the file. The returned instance will have a file system of BLOBSTORE.

Parameters:

mimeType - the mime-type of the file to be created. This parameter may be used to inform the BlobStore of the mime-type for the file. The mime-type will be returned by the BlobStore in an HTTP response if the file is requested directly from the BlobStore using the blob-key.

Returns:

A AppEngineFile representing the newly created file.

Throws:

java.io.IOException - If there is any problem communicating with the backend system

createNewBlobFile

AppEngineFile createNewBlobFile(java.lang.String mimeType,
                                java.lang.String blobInfoUploadedFileName)
                                throws java.io.IOException

Creates a new empty file in the BlobStore of the specified mime-type and returns an AppEngineFile representing the file. The returned instance will have a file system of BLOBSTORE.

Parameters:

mimeType - the mime-type of the file to be created. This parameter may be used to inform the BlobStore of the mime-type for the file. The mime-type will be returned by the BlobStore in an HTTP response if the file is requested directly from the BlobStore using the blob-key.

blobInfoUploadedFileName - BlobStore will store this name in the BlobInfo's fileName field. This string will not be the name of the returned AppEngineFile. It will be returned by the BlobStore in an HTTP response if the file is requested directly from the BlobStore using the blob-key.

Returns:

A AppEngineFile representing the newly created file.

Throws:

java.io.IOException - If there is any problem communicating with the backend system

createNewGSFile

AppEngineFile createNewGSFile(GSFileOptions fileOptions)
                              throws java.io.IOException

Creates a new writable file in Google Storage of the specified mime-type and returns an AppEngineFile representing the file. The returned instance can only be used for writing and must be finalized before reading it. The returned file will have a file system of GS. For complete write/read lifecycle, please refer to the comments at the top of this file.

Parameters:

fileOptions - GSFileOptions for creating a Google Storage file.

Returns:

A writable AppEngineFile.

Throws:

java.io.IOException - If there is any problem communicating with the backend system

openWriteChannel

FileWriteChannel openWriteChannel(AppEngineFile file,
                                  boolean lock)
                                  throws java.io.FileNotFoundException,
                                         FinalizationException,
                                         LockException,
                                         java.io.IOException

Given an AppEngineFile, returns a FileWriteChannel that may be used for appending bytes to the file.

Parameters:

file - the file to which to append bytes. The file must exist and it must not yet have been finalized. Furthermore, if the file is a GS file then it must be writable.

lock - should the file be locked for exclusive access?

Throws:

java.io.FileNotFoundException - if the file does not exist in the backend repository. The file may have been deleted by another request, or the file may have been lost due to system failure or a scheduled relocation. Each backend repository offers different guarantees regarding when this is possible.

FinalizationException - if the file has already been finalized. The file may have been finalized by another request.

LockException - if the file is locked in a different App Engine request, or if lock = true and the file is opened in a different App Engine request

java.io.IOException - if any other unexpected problem occurs

openReadChannel

FileReadChannel openReadChannel(AppEngineFile file,
                                boolean lock)
                                throws java.io.FileNotFoundException,
                                       LockException,
                                       java.io.IOException

Given an AppEngineFile, returns a FileReadChannel that may be used for reading bytes from the file.

Parameters:

file - The file from which to read bytes. The file must exist and it must have been finalized. Furthermore, if the file is a GS file then it must be readable.

lock - Should the file be locked for exclusive access?

Throws:

java.io.FileNotFoundException - if the file does not exist in the backend repository. The file may have been deleted by another request, or the file may have been lost due to system failure or a scheduled relocation. Each backend repository offers different guarantees regarding when this is possible.

FinalizationException - if the file has not yet been finalized

LockException - if the file is locked in a different App Engine request, or if lock = true and the file is opened in a different App Engine request

java.io.IOException - if any other problem occurs contacting the backend system

getBlobKey

BlobKey getBlobKey(AppEngineFile file)

Given a BLOBSTORE file that has been finalized, returns the BlobKey for the corresponding blob.

Parameters:

file - A BLOBSTORE file that has been finalized

Returns:

The corresponding BlobKey, or null if none can be found. This can occur if the file has not been finalized, or if it does not exist.

Throws:

java.lang.IllegalArgumentException - if file is not a BLOBSTORE file.

getBlobFile

AppEngineFile getBlobFile(BlobKey blobKey)
                          throws java.io.FileNotFoundException

Given a BlobKey returns the corresponding AppEngineFile. The file has been finalized.

Parameters:

blobKey - A blobkey

Returns:

The corresponding file.

Throws:

java.io.FileNotFoundException - if there is no blob with the given blob key.

openRecordWriteChannel

RecordWriteChannel openRecordWriteChannel(AppEngineFile file,
                                          boolean lock)
                                          throws java.io.FileNotFoundException,
                                                 FinalizationException,
                                                 LockException,
                                                 java.io.IOException

Given an AppEngineFile returns a RecordWriteChannel that may be used for writing to the file using the leveldb log format.

Parameters:

file - the file to which to write records. The file must exist, be closed, and it must not yet have been finalized.

lock - should the file be locked for exclusive access?

Throws:

java.io.FileNotFoundException - if the file does not exist in the backend repository. The file may have been deleted by another request, or the file may have been lost due to system failure or a scheduled relocation. Each backend repository offers different guarantees regarding when this is possible.

FinalizationException - if the file has already been finalized. The file may have been finalized by another request.

LockException - if the file is locked in a different App Engine request, or if lock = true and the file is opened in a different App Engine request

java.io.IOException - if any other unexpected problem occurs

openRecordReadChannel

RecordReadChannel openRecordReadChannel(AppEngineFile file,
                                        boolean lock)
                                        throws java.io.FileNotFoundException,
                                               LockException,
                                               java.io.IOException

Given an AppEngineFile, returns a RecordReadChannel that may be used for reading records from a file written using the leveldb log format.

Parameters:

file - The file from which to read records. The file must exist, be closed, and it must have been finalized.

lock - Should the file be locked for exclusive access?

Throws:

java.io.FileNotFoundException - if the file does not exist in the backend repository. The file may have been deleted by another request, or the file may have been lost due to system failure or a scheduled relocation. Each backend repository offers different guarantees regarding when this is possible.

FinalizationException - if the file has not yet been finalized

LockException - if the file is locked in a different App Engine request, or if lock = true and the file is opened in a different App Engine request

java.io.IOException - if any other problem occurs contacting the backend system