org.springframework.cloud.gcp.storage

Class GoogleStorageResource

java.lang.Object

org.springframework.cloud.gcp.storage.GoogleStorageResource

All Implemented Interfaces:

org.springframework.core.io.InputStreamSource, org.springframework.core.io.Resource, org.springframework.core.io.WritableResource

public class GoogleStorageResource
extends Object
implements org.springframework.core.io.WritableResource

Implements WritableResource for reading and writing objects in Google Cloud Storage (GCS). An instance of this class represents a handle to a bucket or a blob.

Author:

Vinicius Carvalho, Mike Eltsufin, Chengyuan Zhao, João André Martins, Daniel Zou, Elena Felder

Constructor Summary

Constructors

Constructor and Description
GoogleStorageResource(Storage storage, GoogleStorageLocation googleStorageLocation, boolean autoCreateFiles) Constructs the resource representation of a bucket or a blob (file) in Google Cloud Storage.
GoogleStorageResource(Storage storage, String locationUri) Constructor that defaults autoCreateFiles to true.
GoogleStorageResource(Storage storage, String locationUri, boolean autoCreateFiles) Constructs the resource representation of a bucket or a blob (file) in Google Cloud Storage.

Method Summary

Modifier and Type	Method and Description
boolean	bucketExists() Checks for the existence of the Bucket associated with the resource.
long	contentLength()
Blob	createBlob() Creates the blob that this GoogleStorageResource represents in Google Cloud Storage.
Blob	createBlob(byte[] contents) Creates the blob that this GoogleStorageResource represents in Google Cloud Storage and fills it with provided content.
Bucket	createBucket() Creates the bucket that this resource references in Google Cloud Storage.
GoogleStorageResource	createRelative(String relativePath) Creates a GoogleStorageResource handle that is relative to this one.
URL	createSignedUrl(TimeUnit timeUnit, long timePeriods, Storage.SignUrlOption... options) Creates a signed URL to an object, if it exists.
boolean	exists()
Blob	getBlob() Gets the underlying storage object in Google Cloud Storage.
String	getBlobName()
Bucket	getBucket() Returns the Bucket associated with the resource.
String	getBucketName()
String	getDescription()
File	getFile()
String	getFilename()
GoogleStorageLocation	getGoogleStorageLocation()
InputStream	getInputStream()
OutputStream	getOutputStream() Returns the output stream for a Google Cloud Storage file.
URI	getURI()
URL	getURL() Since the gs: protocol will normally not have a URL stream handler registered, this method will always throw a MalformedURLException.
boolean	isAutoCreateFiles()
boolean	isBucket()
boolean	isOpen()
boolean	isReadable()
boolean	isWritable()
long	lastModified()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.springframework.core.io.WritableResource

writableChannel

Methods inherited from interface org.springframework.core.io.Resource

isFile, readableChannel

Constructor Detail

GoogleStorageResource

public GoogleStorageResource(Storage storage,
                             String locationUri,
                             boolean autoCreateFiles)

Constructs the resource representation of a bucket or a blob (file) in Google Cloud Storage.

Parameters:

storage - the Google Cloud Storage client

locationUri - the URI of the bucket or blob, e.g., gs://your-bucket/ or gs://your-bucket/your-file-name

autoCreateFiles - determines the auto-creation of the file in Google Cloud Storage if an operation that depends on its existence is triggered (e.g., getting the output stream of a file)

Throws:

IllegalArgumentException - if the location URI is invalid

GoogleStorageResource

public GoogleStorageResource(Storage storage,
                             String locationUri)

Constructor that defaults autoCreateFiles to true.

Parameters:

locationUri - the cloud storage address

storage - the storage client

See Also:

GoogleStorageResource(Storage, String, boolean)

GoogleStorageResource

public GoogleStorageResource(Storage storage,
                             GoogleStorageLocation googleStorageLocation,
                             boolean autoCreateFiles)

Constructs the resource representation of a bucket or a blob (file) in Google Cloud Storage.

Parameters:

storage - the Google Cloud Storage client

googleStorageLocation - the GoogleStorageLocation of the resource.

autoCreateFiles - determines the auto-creation of the file in Google Cloud Storage if an operation that depends on its existence is triggered (e.g., getting the output stream of a file)

Throws:

IllegalArgumentException - if the location is an invalid Google Storage location

Since:

1.2

Method Detail

isAutoCreateFiles

public boolean isAutoCreateFiles()

exists

public boolean exists()

Specified by:

exists in interface org.springframework.core.io.Resource

isReadable

public boolean isReadable()

Specified by:

isReadable in interface org.springframework.core.io.Resource

isOpen

public boolean isOpen()

Specified by:

isOpen in interface org.springframework.core.io.Resource

getURL

public URL getURL()
           throws IOException

Since the gs: protocol will normally not have a URL stream handler registered, this method will always throw a MalformedURLException.

Specified by:

getURL in interface org.springframework.core.io.Resource

Returns:

the URL for the GCS resource, if a URL stream handler is registered for the gs protocol.

Throws:

IOException

getURI

public URI getURI()

Specified by:

getURI in interface org.springframework.core.io.Resource

getBlob

public Blob getBlob()
             throws IOException

Gets the underlying storage object in Google Cloud Storage.

Returns:

the storage object, will be null if it does not exist in Google Cloud Storage.

Throws:

IOException - if an issue occurs getting the Blob

IllegalStateException - if the resource reference is to a bucket, and not a blob.

createSignedUrl

public URL createSignedUrl(TimeUnit timeUnit,
                           long timePeriods,
                           Storage.SignUrlOption... options)
                    throws IOException

Creates a signed URL to an object, if it exists. This method will fail if this storage resource was not created using service account credentials.

Parameters:

timeUnit - the time unit used to determine how long the URL is valid.

timePeriods - the number of periods to determine how long the URL is valid.

options - specifies additional options for signing URLs

Returns:

the URL if the object exists, and null if it does not.

Throws:

IllegalStateException - if the resource reference is to a bucket, and not a blob.

IOException - if there are errors in accessing Google Storage

createBlob

public Blob createBlob()
                throws StorageException

Creates the blob that this GoogleStorageResource represents in Google Cloud Storage.

Returns:

the created blob object

Throws:

StorageException - if any errors during blob creation arise, such as if the blob already exists

IllegalStateException - if the resource reference is to a bucket, and not a blob.

createBlob

public Blob createBlob(byte[] contents)
                throws StorageException

Creates the blob that this GoogleStorageResource represents in Google Cloud Storage and fills it with provided content.

Parameters:

contents - the initial file contents to write

Returns:

the created blob object

Throws:

StorageException - if any errors during blob creation arise, such as if the blob already exists

IllegalStateException - if the resource reference is to a bucket, and not a blob.

Since:

1.2.2

createBucket

public Bucket createBucket()

Creates the bucket that this resource references in Google Cloud Storage.

Returns:

the Bucket object for the bucket

Throws:

StorageException - if any errors during bucket creation arise, such as if the bucket already exists

getBucket

public Bucket getBucket()

Returns the Bucket associated with the resource.

Returns:

the bucket if it exists, or null otherwise

bucketExists

public boolean bucketExists()

Checks for the existence of the Bucket associated with the resource.

Returns:

true if the bucket exists

getFile

public File getFile()
             throws IOException

Specified by:

getFile in interface org.springframework.core.io.Resource

Throws:

IOException

contentLength

public long contentLength()
                   throws IOException

Specified by:

contentLength in interface org.springframework.core.io.Resource

Throws:

IOException

lastModified

public long lastModified()
                  throws IOException

Specified by:

lastModified in interface org.springframework.core.io.Resource

Throws:

IOException

createRelative

public GoogleStorageResource createRelative(String relativePath)
                                     throws IOException

Creates a GoogleStorageResource handle that is relative to this one. It inherits autoCreateFiles from this object. Note that it does not actually create the blob.

Note that this method does not actually create the blob.

Specified by:

createRelative in interface org.springframework.core.io.Resource

Parameters:

relativePath - the URL to a Google Cloud Storage file

Returns:

the GoogleStorageResource handle for the relative path

Throws:

IOException - if an issue occurs creating the relative GoogleStorageResource

getFilename

public String getFilename()

Specified by:

getFilename in interface org.springframework.core.io.Resource

getDescription

public String getDescription()

Specified by:

getDescription in interface org.springframework.core.io.Resource

getInputStream

public InputStream getInputStream()
                           throws IOException

Specified by:

getInputStream in interface org.springframework.core.io.InputStreamSource

Throws:

IOException

isWritable

public boolean isWritable()

Specified by:

isWritable in interface org.springframework.core.io.WritableResource

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Returns the output stream for a Google Cloud Storage file.

Specified by:

getOutputStream in interface org.springframework.core.io.WritableResource

Returns:

the object's output stream or null if the object doesn't exist and cannot be created

Throws:

IOException - if an issue occurs getting the OutputStream

getBlobName

public String getBlobName()

Returns:

the blob name of the Google Storage Resource; null if the resource is a bucket

isBucket

public boolean isBucket()

Returns:

true if the resource is a bucket; false otherwise

getBucketName

public String getBucketName()

Returns:

the bucket name of the Google Storage Resource

getGoogleStorageLocation

public GoogleStorageLocation getGoogleStorageLocation()

Returns:

the GoogleStorageLocation describing the location of the resource in GCS

Since:

1.2