FileService (Google App Engine API for Java)

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. 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 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 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
        Deprecated. 
        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
        Deprecated. 
        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
        Deprecated. 
        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
        Deprecated. 
        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)
        Deprecated. 
        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)
        Deprecated. 
        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
        Deprecated. 
        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
        Deprecated. 
        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
        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 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
        Deprecated. 
        Given AppEngineFiles 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.