# FileService
Date: 2012-02-24

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