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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `void` | `delete(AppEngineFile... files)` Given `AppEngineFile`s with finalized filename, permanently delete them in bulk.
    `AppEngineFile` | `getBlobFile(BlobKey blobKey)` Given a `BlobKey`, returns an instance of `AppEngineFile` with the given key.
    `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.
    `FileStat` | `stat(AppEngineFile file)` Given a finalized `AppEngineFile`, return a `FileStat` object that contains information about it.

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

      Given a `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.
      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

      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

    - #### getDefaultGsBucketName

          java.lang.String getDefaultGsBucketName()
                                                  throws java.io.IOException

      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

      Given a finalized `AppEngineFile`, return a `FileStat` object that contains information about it. Limitations in current implementation:
      1. File must be finalized before stat can be called.
      2. Only `filename`, `finalized`, and `length` are filled in the `FileStat` 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

      Given `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.
      Parameters:
        `files` - to delete.
      Throws:
        `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.