tachyon.underfs

Class UnderFileSystemRegistry

java.lang.Object

tachyon.underfs.UnderFileSystemRegistry

public final class UnderFileSystemRegistry
extends Object

Central registry of available UnderFileSystemFactory instances that uses the ServiceLoader mechanism to automatically discover available factories and provides a central place for obtaining actual UnderFileSystem instances.

Registering New Factories

New factories can be registered either using the ServiceLoader based automatic discovery mechanism or manually using the static register(UnderFileSystemFactory) method. The down-side of the automatic discovery mechanism is that the discovery order is not controllable. As a result if your implementation is designed as a replacement for one of the standard implementations, depending on the order in which the JVM discovers the services your own implementation may not take priority. You can enable DEBUG level logging for this class to see the order in which factories are discovered and which is selected when obtaining a UnderFileSystem instance for a path. If this shows that your implementation is not getting discovered or used, you may wish to use the manual registration approach.

Automatic Discovery

To use the ServiceLoader based mechanism you need to have a file named tachyon.underfs.UnderFileSystemFactory placed in the META-INF\services directory of your project. This file should contain the full name of your factory types (one per line), your factory types must have a public unparameterised constructor available (see ServiceLoader for more detail on this). You can enable DEBUG level logging to see factories as they are discovered if you wish to check that your implementation gets discovered.

Note that if you are bundling Tachyon plus your code in a shaded JAR using Maven, make sure to use the ServicesResourceTransformer as otherwise your services file will override the core provided services file and leave the standard factories and under file system implementations unavailable.

Manual Registration

To manually register a factory, simply pass an instance of your factory to the register(UnderFileSystemFactory) method. This can be useful when your factory cannot be instantiated without arguments or in cases where automatic discovery does not give your factory priority. Factories registered this way will be registered at the start of the factories list so will have the first opportunity to indicate whether they support a requested path.

Constructor Summary

Constructors

Constructor and Description
UnderFileSystemRegistry()

Method Summary

Methods

Modifier and Type	Method and Description
static List<UnderFileSystemFactory>	available() Returns a read-only view of the available factories
static UnderFileSystem	create(String path, TachyonConf tachyonConf, Object ufsConf) Creates a client for operations involved with the under file system.
static UnderFileSystemFactory	find(String path, TachyonConf tachyonConf) Finds the first Under File System factory that supports the given path
static List<UnderFileSystemFactory>	findAll(String path, TachyonConf tachyonConf) Finds all the Under File System factories that support the given path
static void	register(UnderFileSystemFactory factory) Registers a new factory
static void	reset() Resets the registry to its default state
static void	unregister(UnderFileSystemFactory factory) Unregisters an existing factory

Methods inherited from class java.lang.Object

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

Constructor Detail

UnderFileSystemRegistry

public UnderFileSystemRegistry()

Method Detail

available

public static List<UnderFileSystemFactory> available()

Returns a read-only view of the available factories

Returns:

Read-only view of the available factories

create

public static UnderFileSystem create(String path,
                     TachyonConf tachyonConf,
                     Object ufsConf)

Creates a client for operations involved with the under file system.

Parameters:

path - Path

tachyonConf - Tachyon Configuration

ufsConf - Optional configuration object for the UFS, may be null

Returns:

Client for the under file system

Throws:

IllegalArgumentException - Thrown if there is no under file system for the given path or if no under file system could successfully be created

find

public static UnderFileSystemFactory find(String path,
                          TachyonConf tachyonConf)

Finds the first Under File System factory that supports the given path

Parameters:

path - Path

tachyonConf - Tachyon configuration

Returns:

Factory if available, null otherwise

findAll

public static List<UnderFileSystemFactory> findAll(String path,
                                   TachyonConf tachyonConf)

Finds all the Under File System factories that support the given path

Parameters:

path - Path

tachyonConf - Tachyon Configuration

Returns:

List of factories that support the given path which may be an empty list

register

public static void register(UnderFileSystemFactory factory)

Registers a new factory

Factories are registered at the start of the factories list so they can override the existing automatically discovered factories. Generally if you use the ServiceLoader mechanism properly it should be unnecessary to call this, however since ServiceLoader discovery order may be susceptible to class loader behavioural differences there may be rare cases when you need to manually register the desired factory.

Parameters:

factory - Factory to register

reset

public static void reset()

Resets the registry to its default state

This clears the registry as it stands and rediscovers the available factories.

unregister

public static void unregister(UnderFileSystemFactory factory)

Unregisters an existing factory

Parameters:

factory - Factory to unregister