io.rxmicro.cdi.Factory Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of rxmicro-cdi Show documentation
The module that is an implementation of the Dependency Injection design pattern, that is integrated to the RxMicro framework.
The newest version!
/*
 * Copyright (c) 2020. https://rxmicro.io
 *
 * 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
 *
 *     http://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.rxmicro.cdi;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.CLASS;

/**
 * Denotes a factory method or a factory, that creates instances of the specified class.
 *
 * 
 * When using the dependency injection mechanisms, the RxMicro framework creates instances of the specified classes and injects links
 * to them to injection points. For successful implementation of this behavior, each class, the instance of which should be injected,
 * must contain an accessible constructor without parameters or a constructor annotated by the
 * {@link Inject} or {@link Autowired} annotation.
 *
 * 

 * In other words, the RxMicro framework determines the instance of which class should be created and creates this instance
 * automatically at the start of the CDI container. If it is necessary to get more control over creation of the implementation
 * instance, it is necessary to use the Factory Method template.
 * If the RxMicro framework detects a method in the class, annotated by the {@link Factory} annotation, then this method is used instead
 * of the constructor when creating the instance of this class.
 *
 * 

 * The factory method must meet the following requirements:
 * 

 *     The method must be {@code static}.
 *     The method must be non-{@code native}.
 *     The method must not be {@code synchronized}.
 *     The method must return the class instance in which it is declared.
 *     The method must not contain parameters.
 * 
 *
 * 
 * Besides factory method the RxMicro framework supports creation of factory classes, that can be used to create instances of other types.
 *
 * 

 * By using factory classes, it is possible to get the following benefits:
 * 

 *     Create dynamic classes. (For example, using the {@link java.lang.reflect.Proxy} class.)
 *     Implement a {@code prototype} scope.
 * 
 *
 * 
 * To create a factory class, it is necessary:
 * 

 *     Create a class implementing the {@link java.util.function.Supplier} interface.
 *     Annotate this class by the {@link Factory} annotation.
 *     Implement the {@link java.util.function.Supplier#get()} method, which should return the instance of the created class.
 * 
 *
 * @author nedis
 * @see java.util.function.Supplier
 * @see java.lang.reflect.Proxy
 * @see Inject
 * @see Autowired
 * @since 0.1
 */
@Documented
@Retention(CLASS)
@Target({METHOD, TYPE})
public @interface Factory {
}