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 BeanCapableImportCandidate 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

{@code
// 1. Define your custom annotation

### Declaration

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

**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 your custom annotation
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Import(MyFeatureImportCandidate.class)
public @interface EnableMyFeature {
    String value() default "";
}

// 2. Implement the Import Candidate
public class MyFeatureImportCandidate extends AnnotatedBeanCapableImportCandidate implements
ImportBeanDefinitionRegistrar {

    @Override
    public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {
        if (!isEnabled(importingClassMetadata)) {
            return;
        }
        ResolvablePlaceholderAnnotationAttributes attrs = getAnnotationAttributes(importingClassMetadata);
        String featureName = attrs.getString("value");
        // Register beans based on featureName...
    }
}

// 3. Use in Configuration
@Configuration
@EnableMyFeature("my-feature")
public class AppConfig {
    // Beans will be imported if enabled
}
```

### Method Examples

#### `getAnnotationType`

```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 |
|--------|-------------|
| `getAnnotationType` | Gets the annotation attributes from the given `AnnotationMetadata`, resolving any placeholders. |
| `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()
```

Gets the annotation attributes from the given `AnnotationMetadata`, resolving any placeholders.



This method retrieves the attributes of the annotation type associated with this import candidate
from the importing class's metadata. It uses `ResolvablePlaceholderAnnotationAttributes` to
ensure that any property placeholders (e.g., `${my.property`}) within the annotation attributes
are resolved against the Spring `Environment`.

### Example Usage
Suppose you have an annotation `@EnableFeature(name = "${feature.name`")} and a configuration class:
{@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`
- `ResolvablePlaceholderAnnotationAttributes`
- `AnnotatedBeanCapableImportSelector`
- `AnnotatedBeanCapableImportBeanDefinitionRegistrar`

---

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