com.google.cloud.hadoop.gcsio

Class GoogleCloudStorageFileSystem

java.lang.Object

com.google.cloud.hadoop.gcsio.GoogleCloudStorageFileSystem

public class GoogleCloudStorageFileSystem
extends Object

Provides a POSIX like file system layered on top of Google Cloud Storage (GCS). All file system aspects (eg, path) are encapsulated in this class, they are not exposed to the underlying layer. That is, all interactions with the underlying layer are strictly in terms of buckets and objects.

Field Summary

Fields

Modifier and Type	Field and Description
static URI	GCS_ROOT
static PathCodec	LEGACY_PATH_CODEC A PathCodec that maintains compatibility with versions of GCS FS < 1.4.5.
static org.slf4j.Logger	LOG
static String	SCHEME
static PathCodec	URI_ENCODED_PATH_CODEC A PathCodec that expects URIs to be of the form: gs://authority/properly/encoded/path.

Constructor Summary

Constructors

Constructor and Description
GoogleCloudStorageFileSystem(com.google.api.client.auth.oauth2.Credential credential, GoogleCloudStorageFileSystemOptions options) Constructs an instance of GoogleCloudStorageFileSystem.
GoogleCloudStorageFileSystem(GoogleCloudStorage gcs) Constructs a GoogleCloudStorageFilesystem based on an already-configured underlying GoogleCloudStorage gcs.
GoogleCloudStorageFileSystem(GoogleCloudStorage gcs, GoogleCloudStorageFileSystemOptions options) Constructs a GoogleCloudStorageFilesystem based on an already-configured underlying GoogleCloudStorage gcs.

Method Summary

Modifier and Type	Method and Description
void	close() Releases resources used by this instance.
void	compose(List<URI> sources, URI destination, String contentType) Composes inputs into a single GCS object.
WritableByteChannel	create(URI path) Creates and opens an object for writing.
WritableByteChannel	create(URI path, CreateFileOptions options) Creates and opens an object for writing.
void	delete(URI path, boolean recursive) Deletes one or more items indicated by the given path.
boolean	exists(URI path) Indicates whether the given item exists.
FileInfo	getFileInfo(URI path) Gets information about the given path item.
List<FileInfo>	getFileInfos(List<URI> paths) Gets information about each path in the given list; more efficient than calling getFileInfo() on each path individually in a loop.
GoogleCloudStorageFileSystemOptions	getOptions() Retrieve the options that were used to create this GoogleCloudStorageFileSystem.
static URI	getParentPath(PathCodec pathCodec, URI path) Deprecated. This static method is included as a transitional utility and the instance method variant should be preferred.
URI	getParentPath(URI path) Gets the parent directory of the given path.
static URI	getPath(String bucketName) Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.
static URI	getPath(String bucketName, String objectName) Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.
static URI	getPath(String bucketName, String objectName, boolean allowEmptyObjectName) Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.
PathCodec	getPathCodec() The PathCodec in use by this file system.
List<FileInfo>	listAllFileInfoForPrefix(URI prefix) Equivalent to a recursive listing of prefix, except that prefix doesn't have to represent an actual object but can just be a partial prefix string, and there is no auto-repair of implicit directories since we can't detect implicit directories without listing by 'delimiter'.
List<FileInfo>	listFileInfo(URI path, boolean enableAutoRepair) If the given path points to a directory then the information about its children is returned, otherwise information about the given file is returned.
List<URI>	listFileNames(FileInfo fileInfo) If the given item is a directory then the paths of its immediate children are returned, otherwise the path of the given item is returned.
List<URI>	listFileNames(FileInfo fileInfo, boolean recursive) If the given item is a directory then the paths of its children are returned, otherwise the path of the given item is returned.
void	mkdir(URI path) Creates a directory at the specified path.
void	mkdirs(URI path) Creates a directory at the specified path.
static CreateObjectOptions	objectOptionsFromFileOptions(CreateFileOptions options) Convert CreateFileOptions to CreateObjectOptions.
SeekableByteChannel	open(URI path) Opens an object for reading.
void	rename(URI src, URI dst) Renames the given item's path.
void	repairDirs(List<URI> exactDirPaths) Creates the list of directories specified in exactDirPaths; doesn't perform validation and doesn't create their parent dirs if their parent dirs don't already exist.
boolean	repairPossibleImplicitDirectory(URI path) Checks that path doesn't already exist as a directory object, and if so, performs an object listing using the full path as the match prefix so that if there are any objects that imply path is a parent directory, we will discover its existence as a returned GCS 'prefix'.
protected void	tryUpdateTimestampsForParentDirectories(List<URI> modifiedObjects, List<URI> excludedParents) For each listed modified object, attempt to update the modification time of the parent directory.
protected void	updateTimestampsForParentDirectories(List<URI> modifiedObjects, List<URI> excludedParents) For each listed modified object, attempt to update the modification time of the parent directory.
static StorageResourceId	validatePathAndGetId(URI uri, boolean allowEmptyObjectNames) Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.

Methods inherited from class java.lang.Object

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

Field Detail

SCHEME

public static final String SCHEME

See Also:

Constant Field Values

GCS_ROOT

public static final URI GCS_ROOT

LOG

public static final org.slf4j.Logger LOG

LEGACY_PATH_CODEC

public static final PathCodec LEGACY_PATH_CODEC

A PathCodec that maintains compatibility with versions of GCS FS < 1.4.5.

URI_ENCODED_PATH_CODEC

public static final PathCodec URI_ENCODED_PATH_CODEC

A PathCodec that expects URIs to be of the form: gs://authority/properly/encoded/path.

Constructor Detail

GoogleCloudStorageFileSystem

public GoogleCloudStorageFileSystem(com.google.api.client.auth.oauth2.Credential credential,
                                    GoogleCloudStorageFileSystemOptions options)
                             throws IOException

Constructs an instance of GoogleCloudStorageFileSystem.

Parameters:

credential - OAuth2 credential that allows access to GCS.

options - Options for how this filesystem should operate and configure its underlying storage.

Throws:

IOException

GoogleCloudStorageFileSystem

public GoogleCloudStorageFileSystem(GoogleCloudStorage gcs)
                             throws IOException

Constructs a GoogleCloudStorageFilesystem based on an already-configured underlying GoogleCloudStorage gcs.

Throws:

IOException

GoogleCloudStorageFileSystem

public GoogleCloudStorageFileSystem(GoogleCloudStorage gcs,
                                    GoogleCloudStorageFileSystemOptions options)
                             throws IOException

Constructs a GoogleCloudStorageFilesystem based on an already-configured underlying GoogleCloudStorage gcs. Any options pertaining to GCS creation will be ignored.

Throws:

IOException

Method Detail

getOptions

public GoogleCloudStorageFileSystemOptions getOptions()

Retrieve the options that were used to create this GoogleCloudStorageFileSystem.

create

public WritableByteChannel create(URI path)
                           throws IOException

Creates and opens an object for writing. If the object already exists, it is deleted.

Parameters:

path - Object full path of the form gs://bucket/object-path.

Returns:

A channel for writing to the given object.

Throws:

IOException

objectOptionsFromFileOptions

public static CreateObjectOptions objectOptionsFromFileOptions(CreateFileOptions options)

Convert CreateFileOptions to CreateObjectOptions.

create

public WritableByteChannel create(URI path,
                                  CreateFileOptions options)
                           throws IOException

Creates and opens an object for writing.

Parameters:

path - Object full path of the form gs://bucket/object-path.

Returns:

A channel for writing to the given object.

Throws:

IOException

open

public SeekableByteChannel open(URI path)
                         throws IOException

Opens an object for reading.

Parameters:

path - Object full path of the form gs://bucket/object-path.

Returns:

A channel for reading from the given object.

Throws:

FileNotFoundException - if the given path does not exist.

IOException - if object exists but cannot be opened.

delete

public void delete(URI path,
                   boolean recursive)
            throws IOException

Deletes one or more items indicated by the given path. If path points to a directory: -- if recursive is true, all items under that path are recursively deleted followed by deletion of the directory. -- else, -- the directory is deleted if it is empty, -- else, an IOException is thrown. The recursive parameter is ignored for a file.

Parameters:

path - Path of the item to delete.

recursive - If true, all sub-items are also deleted.

Throws:

FileNotFoundException - if the given path does not exist.

IOException

exists

public boolean exists(URI path)
               throws IOException

Indicates whether the given item exists.

Parameters:

path - Path of the item to check.

Returns:

true if the given item exists, false otherwise.

Throws:

IOException

repairDirs

public void repairDirs(List<URI> exactDirPaths)
                throws IOException

Creates the list of directories specified in exactDirPaths; doesn't perform validation and doesn't create their parent dirs if their parent dirs don't already exist. Use with caution.

Throws:

IOException

mkdirs

public void mkdirs(URI path)
            throws IOException

Creates a directory at the specified path. Also creates any parent directories as necessary. Similar to 'mkdir -p' command.

Parameters:

path - Path of the directory to create.

Throws:

IOException

rename

public void rename(URI src,
                   URI dst)
            throws IOException

Renames the given item's path. The operation is disallowed if any of the following is true: -- src == GCS_ROOT -- src is a file and dst == GCS_ROOT -- src does not exist -- dst is a file that already exists -- parent of the destination does not exist. Otherwise, the expected behavior is as follows: -- if src is a directory -- dst is an existing file => disallowed -- dst is a directory => rename the directory. -- if src is a file -- dst is a file => rename the file. -- dst is a directory => similar to the previous case after appending src file-name to dst Note: This function is very expensive to call for directories that have many sub-items.

Parameters:

src - Path of the item to rename.

dst - New path of the item.

Throws:

FileNotFoundException - if src does not exist.

IOException

compose

public void compose(List<URI> sources,
                    URI destination,
                    String contentType)
             throws IOException

Composes inputs into a single GCS object. This performs a GCS Compose. Objects will be composed according to the order they appear in the input. The destination object, if already present, will be overwritten. Sources and destination are assumed to be in the same bucket.

Parameters:

sources - the list of URIs to be composed

destination - the resulting URI with composed sources

contentType - content-type of the composed object

Throws:

IOException - if the Compose operation was unsuccessful

listFileNames

public List<URI> listFileNames(FileInfo fileInfo)
                        throws IOException

If the given item is a directory then the paths of its immediate children are returned, otherwise the path of the given item is returned.

Parameters:

fileInfo - FileInfo of an item.

Returns:

Paths of children (if directory) or self path.

Throws:

IOException

listFileNames

public List<URI> listFileNames(FileInfo fileInfo,
                               boolean recursive)
                        throws IOException

If the given item is a directory then the paths of its children are returned, otherwise the path of the given item is returned.

Parameters:

fileInfo - FileInfo of an item.

recursive - If true, path of all children are returned; else, only immediate children are returned.

Returns:

Paths of children (if directory) or self path.

Throws:

IOException

repairPossibleImplicitDirectory

public boolean repairPossibleImplicitDirectory(URI path)
                                        throws IOException

Checks that path doesn't already exist as a directory object, and if so, performs an object listing using the full path as the match prefix so that if there are any objects that imply path is a parent directory, we will discover its existence as a returned GCS 'prefix'. In such a case, the directory object will be explicitly created.

Returns:

true if a repair was successfully made, false if a repair was unnecessary or failed.

Throws:

IOException

listAllFileInfoForPrefix

public List<FileInfo> listAllFileInfoForPrefix(URI prefix)
                                        throws IOException

Equivalent to a recursive listing of prefix, except that prefix doesn't have to represent an actual object but can just be a partial prefix string, and there is no auto-repair of implicit directories since we can't detect implicit directories without listing by 'delimiter'. The 'authority' component of the prefix *must* be the complete authority, however; we can only list prefixes of *objects*, not buckets.

Parameters:

prefix - the prefix to use to list all matching objects.

Throws:

IOException

listFileInfo

public List<FileInfo> listFileInfo(URI path,
                                   boolean enableAutoRepair)
                            throws IOException

If the given path points to a directory then the information about its children is returned, otherwise information about the given file is returned. Note: This function is expensive to call, especially for a directory with many children. Use the alternative listFileNames(FileInfo) if you only need names of children and no other attributes.

Parameters:

path - Given path.

enableAutoRepair - if true, attempt to repair implicit directories when detected.

Returns:

Information about a file or children of a directory.

Throws:

FileNotFoundException - if the given path does not exist.

IOException

getFileInfo

public FileInfo getFileInfo(URI path)
                     throws IOException

Gets information about the given path item.

Parameters:

path - The path we want information about.

Returns:

Information about the given path item.

Throws:

IOException

getFileInfos

public List<FileInfo> getFileInfos(List<URI> paths)
                            throws IOException

Gets information about each path in the given list; more efficient than calling getFileInfo() on each path individually in a loop.

Parameters:

paths - List of paths.

Returns:

Information about each path in the given list.

Throws:

IOException

close

public void close()

Releases resources used by this instance.

mkdir

public void mkdir(URI path)
           throws IOException

Creates a directory at the specified path. There are two conventions for using objects as directories in GCS. 1. An object of zero size with name ending in / 2. An object of zero size with name ending in _$folder$ #1 is the recommended convention by the GCS team. We use it when creating a directory. However, some old tools still use #2. We will decide based on customer use cases whether to support #2 as well. For now, we only support #1. Note that a bucket is always considered a directory. Doesn't create parent directories; normal use cases should only call mkdirs().

Throws:

IOException

updateTimestampsForParentDirectories

protected void updateTimestampsForParentDirectories(List<URI> modifiedObjects,
                                                    List<URI> excludedParents)
                                             throws IOException

For each listed modified object, attempt to update the modification time of the parent directory.

Parameters:

modifiedObjects - The objects that have been modified

excludedParents - A list of parent directories that we shouldn't attempt to update.

Throws:

IOException

tryUpdateTimestampsForParentDirectories

protected void tryUpdateTimestampsForParentDirectories(List<URI> modifiedObjects,
                                                       List<URI> excludedParents)

For each listed modified object, attempt to update the modification time of the parent directory. This method will log & swallow exceptions thrown by the GCSIO layer.

Parameters:

modifiedObjects - The objects that have been modified

excludedParents - A list of parent directories that we shouldn't attempt to update.

getParentPath

public URI getParentPath(URI path)

Gets the parent directory of the given path.

Parameters:

path - Path to convert.

Returns:

Path of parent directory of the given item or null for root path.

getPathCodec

public PathCodec getPathCodec()

The PathCodec in use by this file system.

validatePathAndGetId

@Deprecated
public static StorageResourceId validatePathAndGetId(URI uri,
                                                                 boolean allowEmptyObjectNames)

Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.

Validate a URI using the legacy path codec and return a StorageResourceId.

getPath

@Deprecated
public static URI getPath(String bucketName,
                                      String objectName,
                                      boolean allowEmptyObjectName)

Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.

Construct a URI using the legacy path codec.

getPath

@Deprecated
public static URI getPath(String bucketName)

Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.

Construct a URI using the legacy path codec.

getPath

@Deprecated
public static URI getPath(String bucketName,
                                      String objectName)

Deprecated. This method is deprecated as each instance of GCS FS can be configured with a codec.

Construct a URI using the legacy path codec.

getParentPath

@Deprecated
public static URI getParentPath(PathCodec pathCodec,
                                            URI path)

Deprecated. This static method is included as a transitional utility and the instance method variant should be preferred.

Gets the parent directory of the given path.

Parameters:

path - Path to convert.

Returns:

Path of parent directory of the given item or null for root path.