io microsphere spring context annotation AnnotatedBeanCapableImportCandidate

AnnotatedBeanCapableImportCandidate

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/AnnotatedBeanCapableImportCandidate.java

Overview

An abstract base class for ImportBeanDefinitionRegistrar implementations that are driven by a specific annotation type A.

This class extends BeanCapableImportCandidate to provide common bean import capabilities, while adding support for processing annotation attributes with placeholder resolution. Subclasses must specify the annotation type A via generics.

Key Features

- Automatically resolves the generic annotation type `A` at runtime.
- Supports enabling/disabling imports via environment properties (see `#isEnabled(Environment, String, Class)`).
- Provides resolved annotation attributes via `ResolvablePlaceholderAnnotationAttributes`.

Usage Example: ImportSelector

Suppose you want to create an import candidate for an annotation @EnableMyFeature:

{@code

### Declaration

```java
public abstract class AnnotatedBeanCapableImportCandidate extends BeanCapableImportCandidate
```

**Author:** Mercy

## Version Information

- **Introduced in:** `1.0.0`
- **Current Project Version:** `0.2.26-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

### Example 1

```java
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface EnableMyFeature {
    String value() default "";
}

public class MyFeatureImportCandidate extends AnnotatedBeanCapableImportCandidate {

    @Override
    protected void selectImports(AnnotationMetadata metadata,
                                 ResolvablePlaceholderAnnotationAttributes attributes,
                                 Set imports) {
        String featureName = attributes.getString("value");
        if (StringUtils.hasText(featureName)) {
            imports.add("com.example.MyFeatureConfig");
        }
    }
}
```

### Example 2

```java
@Configuration
@Import(MyFeatureImportCandidate.class)
@EnableMyFeature("test")
public class AppConfig {
    // ...
}
```

### Example 3

```java
public class MyFeatureRegistrar extends AnnotatedBeanCapableImportCandidate {

    @Override
    protected void registerBeanDefinitions(AnnotationMetadata metadata,
                                           BeanDefinitionRegistry registry,
                                           ResolvablePlaceholderAnnotationAttributes attributes) {
        String featureName = attributes.getString("value");
        if (StringUtils.hasText(featureName)) {
            GenericBeanDefinition beanDefinition = new GenericBeanDefinition();
            beanDefinition.setBeanClass(MyFeatureService.class);
            beanDefinition.getPropertyValues().add("name", featureName);
            registry.registerBeanDefinition("myFeatureService", beanDefinition);
        }
    }
}
```

### Method Examples

#### `getAnnotationType`

```java
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface EnableMyFeature {
    String value() default "";
}

public class MyFeatureImportCandidate extends AnnotatedBeanCapableImportCandidate {

    @Override
    protected void selectImports(AnnotationMetadata metadata,
                                 ResolvablePlaceholderAnnotationAttributes attributes,
                                 Set imports) {
        String featureName = attributes.getString("value");
        if (StringUtils.hasText(featureName)) {
            imports.add("com.example.MyFeatureConfig");
        }
    }
}
```

```java
@Override
protected void registerBeanDefinitions(AnnotationMetadata metadata,
                                       BeanDefinitionRegistry registry,
                                       BeanNameGenerator importBeanNameGenerator,
                                       ResolvablePlaceholderAnnotationAttributes attributes) {
    String prefix = attributes.getString("prefix");
    if (StringUtils.hasText(prefix)) {
        GenericBeanDefinition beanDefinition = new GenericBeanDefinition();
        beanDefinition.setBeanClass(MyService.class);
        beanDefinition.getPropertyValues().add("prefix", prefix);
        registry.registerBeanDefinition("myService", beanDefinition);
    }
}
```

```java
@Configuration
@EnableFeature(name = "${feature.name}")
public class MyConfig { ... }
```

## 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.AnnotatedBeanCapableImportCandidate;
```

## API Reference

### Public Methods

| Method | Description |
|--------|-------------|
| `registerBeanDefinitions` |  |
| `registerBeanDefinitions` |  |
| `getAnnotationType` | Selects the class names to be imported based on the annotation attributes. |
| `getEnabledPropertyName` | Checks if the import candidate is enabled based on the environment properties. |
| `getGlobalEnabledPropertyName` | Gets the global property name that controls whether the import candidate is enabled for the specified annotation type. |

### Method Details

#### `getAnnotationType`

```java
public Class getAnnotationType()
```

Selects the class names to be imported based on the annotation attributes.



Subclasses should override this method to add specific class names to the `imports` set
based on the resolved annotation attributes. The default implementation does nothing.

### Example Usage
Suppose you have an annotation `@EnableMyFeature(value = "com.example")`:
{@code

#### `getEnabledPropertyName`

```java
public static String getEnabledPropertyName(String importingClassName, Class extends Annotation> annotationType)
```

Checks if the import candidate is enabled based on the environment properties.



The check is performed in the following order:

    - Check for a class-specific property: `microsphere.spring.@.enabled`
    - If not found, check for a global property: `microsphere.spring..enabled`
    - If neither is found, default to `true`


### Example Usage
Given an importing class `com.example.MyConfiguration` and an annotation type
`io.microsphere.spring.annotation.EnableMicrosphere`:

    - If property `microsphere.spring.com.example.MyConfiguration@io.microsphere.spring.annotation.EnableMicrosphere.enabled=false` is set, returns `false`.
    - If the above is not set, but `microsphere.spring.io.microsphere.spring.annotation.EnableMicrosphere.enabled=false` is set, returns `false`.
    - If neither is set, returns `true` (default).

#### `getGlobalEnabledPropertyName`

```java
public static String getGlobalEnabledPropertyName(Class extends Annotation> annotationType)
```

Gets the global property name that controls whether the import candidate is enabled for the specified annotation type.



The property name is constructed as:
`microsphere.spring..enabled`
### Example Usage
If the annotation type is `io.microsphere.spring.annotation.EnableMicrosphere`,
the returned property name will be:
`microsphere.spring.io.microsphere.spring.annotation.EnableMicrosphere.enabled`

## See Also

- `BeanCapableImportCandidate`
- `ImportBeanDefinitionRegistrar`
- `ResolvablePlaceholderAnnotationAttributes`

---

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