io.micronaut.context.BeanContext Maven / Gradle / Ivy
/*
* Copyright 2017-2020 original authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.micronaut.context;
import io.micronaut.context.event.ApplicationEventPublisher;
import io.micronaut.core.annotation.AnnotationMetadataResolver;
import io.micronaut.core.attr.MutableAttributeHolder;
import io.micronaut.inject.BeanIdentifier;
import io.micronaut.inject.validation.BeanDefinitionValidator;
import org.jetbrains.annotations.NotNull;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import java.util.Map;
import java.util.Objects;
import java.util.Optional;
/**
* The core BeanContext abstraction which allows for dependency injection of classes annotated with
* {@link javax.inject.Inject}.
*
*
Apart of the standard {@code javax.inject} annotations for dependency injection, additional annotations within
* the {@code io.micronaut.context.annotation} package allow control over configuration of the bean context.
*
* @author Graeme Rocher
* @since 1.0
*/
public interface BeanContext extends
LifeCycle,
ExecutionHandleLocator,
BeanLocator,
BeanDefinitionRegistry,
ApplicationEventPublisher,
AnnotationMetadataResolver,
MutableAttributeHolder {
/**
* Inject an existing instance.
*
* @param instance The instance to inject
* @param The bean generic type
* @return The instance to inject
*/
@NonNull T inject(@NonNull T instance);
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
* Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param The bean generic type
* @return The instance
*/
default @NonNull T createBean(@NonNull Class beanType) {
return createBean(beanType, (Qualifier) null);
}
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
* Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param qualifier The qualifier
* @param The bean generic type
* @return The instance
*/
@NonNull T createBean(@NonNull Class beanType, @Nullable Qualifier qualifier);
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
*
If the bean defines any {@link io.micronaut.context.annotation.Parameter} values then the values passed
* in the {@code argumentValues} parameter will be used
*
*
Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param qualifier The qualifier
* @param argumentValues The argument values
* @param The bean generic type
* @return The instance
*/
@NonNull T createBean(@NonNull Class beanType, @Nullable Qualifier qualifier, @Nullable Map argumentValues);
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
*
If the bean defines any {@link io.micronaut.context.annotation.Parameter} values then the values passed in
* the {@code argumentValues} parameter will be used
*
*
Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param qualifier The qualifier
* @param args The argument values
* @param The bean generic type
* @return The instance
*/
@NonNull T createBean(@NonNull Class beanType, @Nullable Qualifier qualifier, @Nullable Object... args);
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
*
If the bean defines any {@link io.micronaut.context.annotation.Parameter} values then the values passed in
* the {@code argumentValues} parameter will be used
*
*
Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param args The argument values
* @param The bean generic type
* @return The instance
*/
@NonNull default T createBean(@NonNull Class beanType, @Nullable Object... args) {
return createBean(beanType, null, args);
}
/**
* Creates a new instance of the given bean performing dependency injection and returning a new instance.
*
*
If the bean defines any {@link io.micronaut.context.annotation.Parameter} values then the values passed in
* the {@code argumentValues} parameter will be used
*
*
Note that the instance returned is not saved as a singleton in the context.
*
* @param beanType The bean type
* @param argumentValues The argument values
* @param The bean generic type
* @return The instance
*/
@NonNull default T createBean(@NonNull Class beanType, @Nullable Map argumentValues) {
return createBean(beanType, null, argumentValues);
}
/**
* Destroys the bean for the given type causing it to be re-created. If a singleton has been loaded it will be
* destroyed and removed from the context, otherwise null will be returned.
*
* @param beanType The bean type
* @param The concrete class
* @return The destroy instance or null if no such bean exists
*/
@Nullable T destroyBean(@NonNull Class beanType);
/**
* Refresh the state of the given registered bean applying dependency injection and configuration wiring again.
*
*
Note that if the bean was produced by a {@link io.micronaut.context.annotation.Factory} then this method will
* refresh the factory too
*
* @param identifier The {@link BeanIdentifier}
* @param The concrete class
* @return An {@link Optional} of the instance if it exists for the given registration
*/
@NonNull Optional refreshBean(@Nullable BeanIdentifier identifier);
/**
* @return The class loader used by this context
*/
@NonNull ClassLoader getClassLoader();
/**
* @return Get the configured bean validator, if any.
*/
@NonNull BeanDefinitionValidator getBeanValidator();
@Override
@NonNull BeanContext registerSingleton(@NonNull Class type, @NonNull T singleton, @Nullable Qualifier qualifier, boolean inject);
@Override
default BeanContext registerSingleton(@NonNull Object singleton) {
Objects.requireNonNull(singleton, "Argument [singleton] must not be null");
Class type = singleton.getClass();
return registerSingleton(type, singleton);
}
@Override
default BeanContext registerSingleton(Class type, T singleton, Qualifier qualifier) {
return registerSingleton(type, singleton, qualifier, true);
}
@Override
default BeanContext registerSingleton(Class type, T singleton) {
return registerSingleton(type, singleton, null, true);
}
@NotNull
@Override
default BeanContext registerSingleton(@NotNull Object singleton, boolean inject) {
return (BeanContext) BeanDefinitionRegistry.super.registerSingleton(singleton, inject);
}
/**
* Run the {@link BeanContext}. This method will instantiate a new {@link BeanContext} and call {@link #start()}.
*
* @return The running {@link BeanContext}
*/
static @NonNull BeanContext run() {
return build().start();
}
/**
* Build a {@link BeanContext}.
*
* @return The built, but not yet running {@link BeanContext}
*/
static @NonNull BeanContext build() {
return new DefaultBeanContext();
}
/**
* Run the {@link BeanContext}. This method will instantiate a new {@link BeanContext} and call {@link #start()}.
*
* @param classLoader The classloader to use
* @return The running {@link BeanContext}
*/
static @NonNull BeanContext run(ClassLoader classLoader) {
return build(classLoader).start();
}
/**
* Build a {@link BeanContext}.
*
* @param classLoader The classloader to use
* @return The built, but not yet running {@link BeanContext}
*/
static @NonNull BeanContext build(ClassLoader classLoader) {
return new DefaultBeanContext(classLoader);
}
}