Package org.springframework.core.io.support

# Class SpringFactoriesLoader

java.lang.Object
org.springframework.core.io.support.SpringFactoriesLoader

public class SpringFactoriesLoader extends Object
General purpose factory loading mechanism for internal use within the framework.

`SpringFactoriesLoader` loads and instantiates factories of a given type from "META-INF/spring.factories" files which may be present in multiple JAR files in the classpath. The `spring.factories` file must be in `Properties` format, where the key is the fully qualified name of the interface or abstract class, and the value is a comma-separated list of implementation class names. For example:

    example.MyService=example.MyServiceImpl1,example.MyServiceImpl2

where `example.MyService` is the name of the interface, and `MyServiceImpl1` and `MyServiceImpl2` are two implementations.

Implementation classes must have a single resolvable constructor that will be used to create the instance, either:

- a primary or single constructor
- a single public constructor
- the default constructor

If the resolvable constructor has arguments, a suitable `ArgumentResolver` should be provided. To customize how instantiation failures are handled, consider providing a `FailureHandler`.

Since:
  3.2
Author:
  Arjen Poutsma, Juergen Hoeller, Sam Brannen, Andy Wilkinson, Madhura Bhave, Phillip Webb

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static interface`
`SpringFactoriesLoader.ArgumentResolver`
Strategy for resolving constructor arguments based on their type.
`static interface`
`SpringFactoriesLoader.FailureHandler`
Strategy for handling a failure that occurs when instantiating a factory.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`FACTORIES_RESOURCE_LOCATION`
The location to look for factories.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`SpringFactoriesLoader(ClassLoader classLoader, Map<String,List<String>> factories)`
Create a new `SpringFactoriesLoader` instance.

## Method Summary

Modifier and Type
Method
Description
`static SpringFactoriesLoader`
`forDefaultResourceLocation()`
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from "META-INF/spring.factories", using the default class loader.
`static SpringFactoriesLoader`
`forDefaultResourceLocation(ClassLoader classLoader)`
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from "META-INF/spring.factories", using the given class loader.
`static SpringFactoriesLoader`
`forResourceLocation(String resourceLocation)`
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from the given location, using the default class loader.
`static SpringFactoriesLoader`
`forResourceLocation(String resourceLocation, ClassLoader classLoader)`
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from the given location, using the given class loader.
`protected <T> T`
`instantiateFactory(String implementationName, Class<T> type, SpringFactoriesLoader.ArgumentResolver argumentResolver, SpringFactoriesLoader.FailureHandler failureHandler)`
`<T> List<T>`
`load(Class<T> factoryType)`
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader and a default argument resolver that expects a no-arg constructor.
`<T> List<T>`
`load(Class<T> factoryType, SpringFactoriesLoader.ArgumentResolver argumentResolver)`
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader and the given argument resolver.
`<T> List<T>`
`load(Class<T> factoryType, SpringFactoriesLoader.ArgumentResolver argumentResolver, SpringFactoriesLoader.FailureHandler failureHandler)`
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader, the given argument resolver, and custom failure handling provided by the given failure handler.
`<T> List<T>`
`load(Class<T> factoryType, SpringFactoriesLoader.FailureHandler failureHandler)`
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader with custom failure handling provided by the given failure handler.
`static <T> List<T>`
`loadFactories(Class<T> factoryType, ClassLoader classLoader)`
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the given class loader.
`protected static Map<String,List<String>>`
`loadFactoriesResource(ClassLoader classLoader, String resourceLocation)`
`static List<String>`
`loadFactoryNames(Class<?> factoryType, ClassLoader classLoader)`
Deprecated.
as of 6.0 in favor of `load(Class, ArgumentResolver, FailureHandler)`

### Methods inherited from class java.lang.Object

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

## Field Details

### FACTORIES_RESOURCE_LOCATION

public static final String FACTORIES_RESOURCE_LOCATION
The location to look for factories.

Can be present in multiple JAR files.

See Also:
  - Constant Field Values

## Constructor Details

### SpringFactoriesLoader

protected SpringFactoriesLoader(@Nullable ClassLoader classLoader, Map<String,List<String>> factories)
Create a new `SpringFactoriesLoader` instance.

Parameters:
  `classLoader` - the classloader used to instantiate the factories
  `factories` - a map of factory class name to implementation class names
Since:
  6.0

## Method Details

### load

public <T> List<T> load(Class<T> factoryType)
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader and a default argument resolver that expects a no-arg constructor.

The returned factories are sorted using `AnnotationAwareOrderComparator`.

If a custom instantiation strategy is required, use `load(...)` with a custom `ArgumentResolver` and/or `FailureHandler`.

If duplicate implementation class names are discovered for a given factory type, only one instance of the duplicated implementation type will be instantiated.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
Throws:
  `IllegalArgumentException` - if any factory implementation class cannot be loaded or if an error occurs while instantiating any factory
Since:
  6.0

### load

public <T> List<T> load(Class<T> factoryType, @Nullable SpringFactoriesLoader.ArgumentResolver argumentResolver)
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader and the given argument resolver.

The returned factories are sorted using `AnnotationAwareOrderComparator`.

If duplicate implementation class names are discovered for a given factory type, only one instance of the duplicated implementation type will be instantiated.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
  `argumentResolver` - strategy used to resolve constructor arguments by their type
Throws:
  `IllegalArgumentException` - if any factory implementation class cannot be loaded or if an error occurs while instantiating any factory
Since:
  6.0

### load

public <T> List<T> load(Class<T> factoryType, @Nullable SpringFactoriesLoader.FailureHandler failureHandler)
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader with custom failure handling provided by the given failure handler.

The returned factories are sorted using `AnnotationAwareOrderComparator`.

If duplicate implementation class names are discovered for a given factory type, only one instance of the duplicated implementation type will be instantiated.

For any factory implementation class that cannot be loaded or error that occurs while instantiating it, the given failure handler is called.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
  `failureHandler` - strategy used to handle factory instantiation failures
Since:
  6.0

### load

public <T> List<T> load(Class<T> factoryType, @Nullable SpringFactoriesLoader.ArgumentResolver argumentResolver, @Nullable SpringFactoriesLoader.FailureHandler failureHandler)
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the configured class loader, the given argument resolver, and custom failure handling provided by the given failure handler.

The returned factories are sorted using `AnnotationAwareOrderComparator`.

If duplicate implementation class names are discovered for a given factory type, only one instance of the duplicated implementation type will be instantiated.

For any factory implementation class that cannot be loaded or error that occurs while instantiating it, the given failure handler is called.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
  `argumentResolver` - strategy used to resolve constructor arguments by their type
  `failureHandler` - strategy used to handle factory instantiation failures
Since:
  6.0

### instantiateFactory

@Nullable protected <T> T instantiateFactory(String implementationName, Class<T> type, @Nullable SpringFactoriesLoader.ArgumentResolver argumentResolver, SpringFactoriesLoader.FailureHandler failureHandler)

### loadFactories

public static <T> List<T> loadFactories(Class<T> factoryType, @Nullable ClassLoader classLoader)
Load and instantiate the factory implementations of the given type from "META-INF/spring.factories", using the given class loader.

The returned factories are sorted using `AnnotationAwareOrderComparator`.

If duplicate implementation class names are discovered for a given factory type, only one instance of the duplicated implementation type will be instantiated.

For more advanced factory loading with `SpringFactoriesLoader.ArgumentResolver` or `SpringFactoriesLoader.FailureHandler` support, use `forDefaultResourceLocation(ClassLoader)` to obtain a `SpringFactoriesLoader` instance.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
  `classLoader` - the ClassLoader to use for loading (can be `null` to use the default)
Throws:
  `IllegalArgumentException` - if any factory implementation class cannot be loaded or if an error occurs while instantiating any factory

### loadFactoryNames

@Deprecated(since="6.0") public static List<String> loadFactoryNames(Class<?> factoryType, @Nullable ClassLoader classLoader)
Deprecated.
as of 6.0 in favor of `load(Class, ArgumentResolver, FailureHandler)`
Load the fully qualified class names of factory implementations of the given type from "META-INF/spring.factories", using the given class loader.

If a particular implementation class name is discovered more than once for the given factory type, duplicates will be ignored.

Parameters:
  `factoryType` - the interface or abstract class representing the factory
  `classLoader` - the ClassLoader to use for loading resources; can be `null` to use the default
Throws:
  `IllegalArgumentException` - if an error occurs while loading factory names
See Also:
  - `loadFactories(java.lang.Class<T>, java.lang.ClassLoader)`

### forDefaultResourceLocation

public static SpringFactoriesLoader forDefaultResourceLocation()
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from "META-INF/spring.factories", using the default class loader.

Returns:
  a `SpringFactoriesLoader` instance
Since:
  6.0
See Also:
  - `forDefaultResourceLocation(ClassLoader)`

### forDefaultResourceLocation

public static SpringFactoriesLoader forDefaultResourceLocation(@Nullable ClassLoader classLoader)
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from "META-INF/spring.factories", using the given class loader.

Parameters:
  `classLoader` - the ClassLoader to use for loading resources; can be `null` to use the default
Returns:
  a `SpringFactoriesLoader` instance
Since:
  6.0
See Also:
  - `forDefaultResourceLocation()`

### forResourceLocation

public static SpringFactoriesLoader forResourceLocation(String resourceLocation)
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from the given location, using the default class loader.

Parameters:
  `resourceLocation` - the resource location to look for factories
Returns:
  a `SpringFactoriesLoader` instance
Since:
  6.0
See Also:
  - `forResourceLocation(String, ClassLoader)`

### forResourceLocation

public static SpringFactoriesLoader forResourceLocation(String resourceLocation, @Nullable ClassLoader classLoader)
Create a `SpringFactoriesLoader` instance that will load and instantiate the factory implementations from the given location, using the given class loader.

Parameters:
  `resourceLocation` - the resource location to look for factories
  `classLoader` - the ClassLoader to use for loading resources; can be `null` to use the default
Returns:
  a `SpringFactoriesLoader` instance
Since:
  6.0
See Also:
  - `forResourceLocation(String)`

### loadFactoriesResource

protected static Map<String,List<String>> loadFactoriesResource(ClassLoader classLoader, String resourceLocation)