Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD