@Deprecated
public interface FileService
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://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();
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 an
AppEngineFile 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 an
AppEngineFile representing the file. |
AppEngineFile |
createNewGSFile(GSFileOptions fileOptions)
Deprecated.
Creates a new writable file in Google Storage of the specified mime-type
and returns an
AppEngineFile representing the file. |
void |
delete(AppEngineFile... files)
Deprecated.
Given
AppEngineFile s with finalized filename,
permanently delete them in bulk. |
AppEngineFile |
getBlobFile(BlobKey blobKey)
Deprecated.
Given a
BlobKey , returns an instance of AppEngineFile with
the given key. |
BlobKey |
getBlobKey(AppEngineFile file)
Deprecated.
Given a
BLOBSTORE file that has been finalized, returns the BlobKey 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 an
AppEngineFile , returns a FileReadChannel that may
be used for reading bytes from the file. |
RecordReadChannel |
openRecordReadChannel(AppEngineFile file,
boolean lock)
Deprecated.
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)
Deprecated.
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)
Deprecated.
Given an
AppEngineFile , returns a FileWriteChannel that may
be used for appending bytes to the file. |
FileStat |
stat(AppEngineFile file)
Deprecated.
Given a finalized
AppEngineFile , return a FileStat object
that contains information about it. |
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
systemAppEngineFile 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
systemAppEngineFile 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
systemFileWriteChannel 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 requestjava.io.IOException
- if any other unexpected problem occursFileReadChannel 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 finalizedLockException
- 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 requestjava.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 finalizedBlobKey
, 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)
BlobKey
, returns an instance of AppEngineFile
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.blobKey
- A blobkeyAppEngineFile
with the given 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 requestjava.io.IOException
- if any other unexpected problem occursRecordReadChannel 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 finalizedLockException
- 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 requestjava.io.IOException
- if any other problem occurs contacting the backend
systemjava.lang.String getDefaultGsBucketName() throws java.io.IOException
java.io.IOException
- if any other problem occurs contacting the backend
systemFileStat stat(AppEngineFile file) throws java.io.IOException
AppEngineFile
, return a FileStat
object
that contains information about it.
Limitations in current implementation:
filename
, finalized
, and length
are filled
in the FileStat
returned.file
- the appEngfile to fetch file stat.FileStat
object that has metadata about the appEngineFile.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.void delete(AppEngineFile... files) throws java.io.IOException
AppEngineFile
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.files
- to delete.java.lang.NullPointerException
- if files is null
or any file is null
.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.