io microsphere spring context annotation BeanCapableImportCandidate

BeanCapableImportCandidate

Type: Class | Module: microsphere-spring-context | Package: io.microsphere.spring.context.annotation | Since: 1.0.0

Source: microsphere-spring-context/src/main/java/io/microsphere/spring/context/annotation/BeanCapableImportCandidate.java

Overview

An abstract base class for Import @Import candidates that supports the full Spring bean lifecycle, including population, initialization, and destruction.

Unlike standard ImportSelector or ImportBeanDefinitionRegistrar implementations, which are typically instantiated and invoked without full bean lifecycle management, this class ensures that the candidate instance is treated as a Spring-managed bean. It achieves this by implementing key awareness interfaces (BeanClassLoaderAware, BeanFactoryAware, EnvironmentAware, ApplicationContextAware, and ResourceLoaderAware) and triggering self-registration and initialization upon setting the ResourceLoader.

Subclasses must implement either ImportSelector or ImportBeanDefinitionRegistrar to define their import logic. They can then leverage injected dependencies and lifecycle callbacks provided by the Spring container, and can't override those methods:

- `#setBeanClassLoader(ClassLoader)`
- `#setBeanFactory(BeanFactory)`
- `#setEnvironment(Environment)`
- `#setResourceLoader(ResourceLoader)`
- `#setApplicationContext(ApplicationContext)`

Key Features

- Supports dependency injection via `AbstractAutowireCapableBeanFactory#populateBean(String, RootBeanDefinition, BeanWrapper)`.
- Supports initialization callbacks via `AutowireCapableBeanFactory#initializeBean`.
- Provides access to `ConfigurableListableBeanFactory`, `ConfigurableEnvironment`,
    `ConfigurableApplicationContext`, and `ResourceLoader`.
- Ensures the candidate is registered as a singleton bean in the context.

Example Usage

{@code
// 1. Define a custom ImportSelector extending BeanCapableImportCandidate
public class MyImportSelector extends BeanCapableImportCandidate implements ImportSelector {

    // You can inject dependencies here if needed, though typically done via getter methods
    // provided by the base class after initialization.

### Declaration

```java
public abstract class BeanCapableImportCandidate implements BeanClassLoaderAware, BeanFactoryAware, EnvironmentAware,
```

**Author:** Mercy

## Version Information

- **Introduced in:** `1.0.0`
- **Current Project Version:** `0.2.27-SNAPSHOT`

## Version Compatibility

This component is tested and compatible with the following Java versions:

| Java Version | Status |
|:---:|:---:|
| Java 17 | ✅ Compatible |
| Java 21 | ✅ Compatible |
| Java 25 | ✅ Compatible |

## Examples

```java
// 1. Define a custom ImportSelector extending BeanCapableImportCandidate
public class MyImportSelector extends BeanCapableImportCandidate implements ImportSelector {

    // You can inject dependencies here if needed, though typically done via getter methods
    // provided by the base class after initialization.

    @Override
    public String[] selectImports(AnnotationMetadata importingClassMetadata) {
        // Access the environment to resolve placeholders or make decisions
        String profile = getEnvironment().getActiveProfiles().length > 0 ?
            getEnvironment().getActiveProfiles()[0] : "default";

        logger.info("Selecting imports for profile: {}", profile);

        // Return classes to import based on logic
        if ("prod".equals(profile)) {
            return new String[]{ProdConfig.class.getName()};
        } else {
            return new String[]{DevConfig.class.getName()};
        }
    }
}

// 2. Use the selector in a configuration class
@Import(MyImportSelector.class)
@Configuration
public class AppConfig {
    // ...
}
```

### Method Examples

#### `setBeanClassLoader`

```java
// Automatically invoked by the Spring container during @Import processing.
  // For example, when using:
  @Import(MyImportSelector.class)
  public class AppConfig { }
```

#### `setBeanFactory`

```java
// Automatically invoked by the Spring container during @Import processing.
  // After this call, getBeanFactory() returns the ConfigurableListableBeanFactory.
  @Import(MyImportBeanDefinitionRegistrar.class)
  public class AppConfig { }
```

#### `setEnvironment`

```java
// Automatically invoked by the Spring container during @Import processing.
  // After this call, getEnvironment() returns the ConfigurableEnvironment.
  @Import(MyImportSelector.class)
  public class AppConfig { }
```

#### `setResourceLoader`

```java
// Automatically invoked by the Spring container during @Import processing.
  // After this call, getResourceLoader() returns the ResourceLoader and the
  // bean is fully initialized with Spring bean lifecycle support.
  @Import(MyImportBeanDefinitionRegistrar.class)
  public class AppConfig { }
```

## Usage

### Maven Dependency

Add the following dependency to your `pom.xml`:

```xml

    io.github.microsphere-projects
    microsphere-spring-context
    ${microsphere-spring.version}

```

> **Tip:** Use the BOM (`microsphere-spring-dependencies`) for consistent version management. See the [Getting Started](https://github.com/microsphere-projects/microsphere-spring#getting-started) guide.

### Import

```java
import io.microsphere.spring.context.annotation.BeanCapableImportCandidate;
```

## API Reference

### Public Methods

| Method | Description |
|--------|-------------|
| `setBeanClassLoader` | Indicates that no class to import |
| `setBeanFactory` | Sets the `BeanFactory` that created this bean, stored as a |
| `setEnvironment` | Sets the `Environment` in which this bean operates, stored as a |
| `setResourceLoader` | Sets the `ResourceLoader` for this bean. This is the last callback in the |
| `setApplicationContext` |  |
| `getClassLoader` | Get the `ClassLoader` instance |
| `getBeanFactory` | The `ConfigurableListableBeanFactory` instance |
| `getApplicationContext` | The `ConfigurableApplicationContext` instance |
| `getEnvironment` | The `ConfigurableEnvironment` instance |
| `getResourceLoader` | The `ResourceLoader` instance |
| `selectImports` |  |
| `registerBeanDefinitions` |  |

### Method Details

#### `setBeanClassLoader`

```java
public final void setBeanClassLoader(ClassLoader classLoader)
```

Indicates that no class to import
/
public static final String[] NO_CLASS_TO_IMPORT = EMPTY_STRING_ARRAY;

protected final Logger logger = getLogger(this.getClass());

protected ClassLoader classLoader;

protected ConfigurableListableBeanFactory beanFactory;

protected ConfigurableApplicationContext applicationContext;

protected ConfigurableEnvironment environment;

protected ResourceLoader resourceLoader;

/**
Sets the `ClassLoader` used by the bean. This method also asserts that the
subclass properly implements `ImportSelector` or `ImportBeanDefinitionRegistrar`.

### Example Usage
{@code
  // Automatically invoked by the Spring container during @Import processing.
  // For example, when using:

#### `setBeanFactory`

```java
public final void setBeanFactory(BeanFactory beanFactory)
```

Sets the `BeanFactory` that created this bean, stored as a
`ConfigurableListableBeanFactory`.

### Example Usage
{@code
  // Automatically invoked by the Spring container during @Import processing.
  // After this call, getBeanFactory() returns the ConfigurableListableBeanFactory.

#### `setEnvironment`

```java
public final void setEnvironment(Environment environment)
```

Sets the `Environment` in which this bean operates, stored as a
`ConfigurableEnvironment`.

### Example Usage
{@code
  // Automatically invoked by the Spring container during @Import processing.
  // After this call, getEnvironment() returns the ConfigurableEnvironment.

#### `setResourceLoader`

```java
public final void setResourceLoader(ResourceLoader resourceLoader)
```

Sets the `ResourceLoader` for this bean. This is the last callback in the
sequence, and triggers the self-initialization of this bean as a Spring-managed bean
to support full bean lifecycle (population, initialization, and destruction).

### Example Usage
{@code
  // Automatically invoked by the Spring container during @Import processing.
  // After this call, getResourceLoader() returns the ResourceLoader and the
  // bean is fully initialized with Spring bean lifecycle support.

#### `getBeanFactory`

```java
public final ConfigurableListableBeanFactory getBeanFactory()
```

The `ConfigurableListableBeanFactory` instance

#### `getApplicationContext`

```java
public final ConfigurableApplicationContext getApplicationContext()
```

The `ConfigurableApplicationContext` instance

## See Also

- `ImportSelector`
- `ImportBeanDefinitionRegistrar`
- `BeanClassLoaderAware`
- `BeanFactoryAware`
- `EnvironmentAware`
- `ApplicationContextAware`
- `ResourceLoaderAware`
- `AbstractAutowireCapableBeanFactory#populateBean(String, RootBeanDefinition, BeanWrapper)`
- `AutowireCapableBeanFactory#initializeBean`

---

*This documentation was auto-generated from the source code of [microsphere-spring](https://github.com/microsphere-projects/microsphere-spring).*