|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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 directly.
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. |
java.lang.String |
getDefaultGsBucketName()
Returns a string that represents the default Google Storage bucket name for the application. |
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 |
|---|
AppEngineFile createNewBlobFile(java.lang.String mimeType)
throws java.io.IOException
AppEngineFile representing the file. The returned
instance will have a file system of
BLOBSTORE.
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.
AppEngineFile representing the newly created file.
java.io.IOException - If there is any problem communicating with the backend
system
AppEngineFile createNewBlobFile(java.lang.String mimeType,
java.lang.String blobInfoUploadedFileName)
throws java.io.IOException
AppEngineFile representing the file. The returned
instance will have a file system of
BLOBSTORE.
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.
AppEngineFile representing the newly created file.
java.io.IOException - If there is any problem communicating with the backend
system
AppEngineFile createNewGSFile(GSFileOptions fileOptions)
throws java.io.IOException
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.
fileOptions - GSFileOptions for creating a Google Storage
file.
AppEngineFile.
java.io.IOException - If there is any problem communicating with the backend
system
FileWriteChannel openWriteChannel(AppEngineFile file,
boolean lock)
throws java.io.FileNotFoundException,
FinalizationException,
LockException,
java.io.IOException
AppEngineFile, returns a FileWriteChannel that may
be used for appending bytes to the file.
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?
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
FileReadChannel openReadChannel(AppEngineFile file,
boolean lock)
throws java.io.FileNotFoundException,
LockException,
java.io.IOException
AppEngineFile, returns a FileReadChannel that may
be used for reading bytes from the file.
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?
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
systemBlobKey getBlobKey(AppEngineFile file)
BLOBSTORE file that has been finalized, returns the BlobKey for
the corresponding blob.
file - A BLOBSTORE file that has been finalized
BlobKey, or null if none can be
found. This can occur if the file has not been finalized, or if it
does not exist.
java.lang.IllegalArgumentException - if file is not a BLOBSTORE
file.
AppEngineFile getBlobFile(BlobKey blobKey)
throws java.io.FileNotFoundException
BlobKey returns the corresponding AppEngineFile.
The file has been finalized.
blobKey - A blobkey
java.io.FileNotFoundException - if there is no blob with the given blob key.
RecordWriteChannel openRecordWriteChannel(AppEngineFile file,
boolean lock)
throws java.io.FileNotFoundException,
FinalizationException,
LockException,
java.io.IOException
AppEngineFile returns a RecordWriteChannel that may be used for
writing to the file using the leveldb log format.
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?
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
RecordReadChannel openRecordReadChannel(AppEngineFile file,
boolean lock)
throws java.io.FileNotFoundException,
LockException,
java.io.IOException
AppEngineFile, returns a RecordReadChannel that may
be used for reading records from a file written using the leveldb log format.
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?
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
java.lang.String getDefaultGsBucketName()
throws java.io.IOException
java.io.IOException - if any other problem occurs contacting the backend
system
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||