com.google.appengine.api.files
Interface FileService
-
Deprecated.This api has been deprecated in favor of the App Engine GCS client.
@Deprecated public interface FileService
This is the interface for interacting with the Google App Engine File Service. AFileService
instance is obtained viaFileServiceFactory.getFileService()
. Currently there are two file systems supported:BLOBSTORE
andGS
When writing files in GS (Google Storage), you have to first create a writable file handle by usingcreateNewGSFile
, 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://storage.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
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method and Description AppEngineFile
createNewBlobFile(java.lang.String mimeType)
Deprecated.Creates a new empty file in the BlobStore of the specified mime-type and returns anAppEngineFile
representing the file.AppEngineFile
createNewBlobFile(java.lang.String mimeType, java.lang.String blobInfoUploadedFileName)
Deprecated.Creates a new empty file in the BlobStore of the specified mime-type and returns anAppEngineFile
representing the file.AppEngineFile
createNewGSFile(GSFileOptions fileOptions)
Deprecated.Creates a new writable file in Google Storage of the specified mime-type and returns anAppEngineFile
representing the file.void
delete(AppEngineFile... files)
Deprecated.GivenAppEngineFile
s with finalized filename, permanently delete them in bulk.AppEngineFile
getBlobFile(BlobKey blobKey)
Deprecated.Given aBlobKey
, returns an instance ofAppEngineFile
with the given key.BlobKey
getBlobKey(AppEngineFile file)
Deprecated.Given aBLOBSTORE
file that has been finalized, returns theBlobKey
for the corresponding blob.java.lang.String
getDefaultGsBucketName()
Deprecated.Returns a string that represents the default Google Storage bucket name for the application.FileReadChannel
openReadChannel(AppEngineFile file, boolean lock)
Deprecated.Given anAppEngineFile
, returns aFileReadChannel
that may be used for reading bytes from the file.RecordReadChannel
openRecordReadChannel(AppEngineFile file, boolean lock)
Deprecated.Given anAppEngineFile
, returns aRecordReadChannel
that may be used for reading records from a file written using the leveldb log format.RecordWriteChannel
openRecordWriteChannel(AppEngineFile file, boolean lock)
Deprecated.Given anAppEngineFile
returns aRecordWriteChannel
that may be used for writing to the file using the leveldb log format.FileWriteChannel
openWriteChannel(AppEngineFile file, boolean lock)
Deprecated.Given anAppEngineFile
, returns aFileWriteChannel
that may be used for appending bytes to the file.FileStat
stat(AppEngineFile file)
Deprecated.Given a finalizedAppEngineFile
, return aFileStat
object that contains information about it.
-
-
-
Method Detail
-
createNewBlobFile
AppEngineFile createNewBlobFile(java.lang.String mimeType) throws java.io.IOException
Deprecated.Creates a new empty file in the BlobStore of the specified mime-type and returns anAppEngineFile
representing the file. The returned instance will have afile system
ofBLOBSTORE
.- 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
Deprecated.Creates a new empty file in the BlobStore of the specified mime-type and returns anAppEngineFile
representing the file. The returned instance will have afile system
ofBLOBSTORE
.- 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 thename
of the returnedAppEngineFile
. 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
Deprecated.Creates a new writable file in Google Storage of the specified mime-type and returns anAppEngineFile
representing the file. The returned instance can only be used for writing and must befinalized
before reading it. The returned file will have afile system
ofGS
. 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
Deprecated.Given anAppEngineFile
, returns aFileWriteChannel
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 aGS
file then it must bewritable
.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 iflock = true
and the file is opened in a different App Engine requestjava.io.IOException
- if any other unexpected problem occurs
-
openReadChannel
FileReadChannel openReadChannel(AppEngineFile file, boolean lock) throws java.io.FileNotFoundException, LockException, java.io.IOException
Deprecated.Given anAppEngineFile
, returns aFileReadChannel
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 aGS
file then it must bereadable
.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 finalizedLockException
- if the file is locked in a different App Engine request, or iflock = true
and the file is opened in a different App Engine requestjava.io.IOException
- if any other problem occurs contacting the backend system
-
getBlobKey
BlobKey getBlobKey(AppEngineFile file)
Deprecated.Given aBLOBSTORE
file that has been finalized, returns theBlobKey
for the corresponding blob.- Parameters:
file
- ABLOBSTORE
file that has been finalized- Returns:
- The corresponding
BlobKey
, ornull
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
- iffile
is not aBLOBSTORE
file.
-
getBlobFile
AppEngineFile getBlobFile(BlobKey blobKey)
Deprecated.Given aBlobKey
, returns an instance ofAppEngineFile
with the given key. This method does not check whether the file actually exists although the file corresponding to the key should be a finalized one.- Parameters:
blobKey
- A blobkey- Returns:
- an instance of
AppEngineFile
with the given key.
-
openRecordWriteChannel
RecordWriteChannel openRecordWriteChannel(AppEngineFile file, boolean lock) throws java.io.FileNotFoundException, FinalizationException, LockException, java.io.IOException
Deprecated.Given anAppEngineFile
returns aRecordWriteChannel
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 iflock = true
and the file is opened in a different App Engine requestjava.io.IOException
- if any other unexpected problem occurs
-
openRecordReadChannel
RecordReadChannel openRecordReadChannel(AppEngineFile file, boolean lock) throws java.io.FileNotFoundException, LockException, java.io.IOException
Deprecated.Given anAppEngineFile
, returns aRecordReadChannel
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 finalizedLockException
- if the file is locked in a different App Engine request, or iflock = true
and the file is opened in a different App Engine requestjava.io.IOException
- if any other problem occurs contacting the backend system
-
getDefaultGsBucketName
java.lang.String getDefaultGsBucketName() throws java.io.IOException
Deprecated.Returns a string that represents the default Google Storage bucket name for the application.- Throws:
java.io.IOException
- if any other problem occurs contacting the backend system
-
stat
FileStat stat(AppEngineFile file) throws java.io.IOException
Deprecated.Given a finalizedAppEngineFile
, return aFileStat
object that contains information about it. Limitations in current implementation:- File must be finalized before stat can be called.
- Only
filename
,finalized
, andlength
are filled in theFileStat
returned.
- Parameters:
file
- the appEngfile to fetch file stat.- Returns:
FileStat
object that has metadata about the appEngineFile.- 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.java.io.IOException
- if any other problem occurs contacting the backend system.
-
delete
void delete(AppEngineFile... files) throws java.io.IOException
Deprecated.GivenAppEngineFile
s with finalized filename, permanently delete them in bulk. Delete on non-existent/non-finalized files is a no-op. Thus a file is guaranteed to be non-existent if no exception is thrown after delete. After validating file type, this method tries to delete as many files as possible and will throw an exception in the end if any single deletion failed.- Parameters:
files
- to delete.- Throws:
java.lang.NullPointerException
- if files isnull
or any file isnull
.java.lang.UnsupportedOperationException
- if a file's type is not supported by delete or file does not have a finalized name.java.io.IOException
- if any other problem occurs contacting the backend system.
-
-