org.testifyproject.glassfish.jersey.internal.inject.InjectionManager Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in org.testifyproject.testifyprojectpliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.org.testifyproject.testifyproject/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package org.testifyproject.glassfish.org.testifyproject.internal.inject;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.List;
/**
* Interface provides the org.testifyproject.testifyprojectmunication API between Jersey and Dependency Injection provider.
*
* Lifecycle methods should be called in this order:
*
* - {@link #org.testifyproject.testifyprojectpleteRegistration()} - notifies that Jersey bootstrap has been finished and DI provider should be ready for a runtime.
* - {@link #shutdown()} - Jersey application has been closed and DI provider should make needed cleaning steps.
*
*
* All {@code getInstance} methods can be called after {@link #org.testifyproject.testifyprojectpleteRegistration()} method has been called because at this all
* org.testifyproject.testifyprojectponents are bound to injection manager and ready for getting.
* In turn, {@link #shutdown()} method stops the possibility to use these methods and closes {@code InjectionManager}.
*
* @author Petr Bouda
*/
public interface InjectionManager {
/**
* Completes {@link InjectionManager} and the underlying DI provider. All registered org.testifyproject.testifyprojectponents are bound to injection
* manager and after an invocation of this method all org.testifyproject.testifyprojectponents are available using e.g. {@link #getInstance(Class)}.
*/
void org.testifyproject.testifyprojectpleteRegistration();
/**
* Shuts down the entire {@link InjectionManager} and the underlying DI provider.
*
* Shutdown phase is dedicated to make some final cleaning steps regarding underlying DI provider.
*/
void shutdown();
/**
* Registers one bean represented using fields in the provided descriptor. The final bean can be direct bean or
* factory object which will create the bean at the time of injection. {@code InjectionManager} is able to register a bean
* represented by a class or direct instance.
*
* @param binding one descriptor.
* @see ClassBinding
* @see InstanceBinding
* @see SupplierClassBinding
* @see SupplierInstanceBinding
*/
void register(Binding binding);
/**
* Registers a collection of beans represented using fields in the provided descriptors. The final bean can be
* direct bean or factory object which will create the bean at the time of injection. {@code InjectionManager} is able to
* register a bean represented by a class or direct instance.
*
* @param descriptors collection of descriptors.
* @see ClassBinding
* @see InstanceBinding
* @see SupplierClassBinding
* @see SupplierInstanceBinding
*/
void register(Iterable descriptors);
/**
* Registers beans which are included in {@link Binder}. {@code Binder} can contains all descriptors extending
* {@link Binding} or other binders which are installed together in tree-structure. This method will get all descriptors
* bound in the given binder and register them in the order how the binders are installed together. In the tree structure,
* the deeper on the left side will be processed first.
*
* @param binder collection of descriptors.
* @see ClassBinding
* @see InstanceBinding
* @see SupplierClassBinding
* @see SupplierInstanceBinding
*/
void register(Binder binder);
/**
* Registers a provider. An implementation of the {@link InjectionManager} should test whether the type of the object can be
* registered using the method {@link #isRegistrable(Class)}. Then a caller has an certainty that the instance of the tested
* class can be registered in {@code InjectionManager}. If {@code InjectionManager} is not able to register the provider
* then {@link IllegalArgumentException} is thrown.
*
* @param provider object that can be registered in {@code InjectionManager}.
* @throws IllegalArgumentException provider cannot be registered.
*/
void register(Object provider) throws IllegalArgumentException;
/**
* Tests whether the provided {@code clazz} can be registered by the implementation of the {@link InjectionManager}.
*
* @param clazz type that is tested whether is registrable by the implementation of {@code InjectionManager}.
* @return {@code true} if the {@code InjectionManager} is able to register this type.
*/
boolean isRegistrable(Class clazz);
/**
* Creates, injects and post-constructs an object with the given class. This is equivalent to calling the
* {@code create-class} method followed by the {@code inject-class} method followed by the {@code post-construct} method.
*
* The object created is not managed by the injection manager.
*
* @param createMe The non-null class to create this object from;
* @return An instance of the object that has been created, injected and post constructed.
*/
T createAndInitialize(Class createMe);
/**
* Gets all services from this injection manager that implements this contract or has this implementation along with
* information about the service which can be kept by {@link ServiceHolder}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param qualifiers The set of qualifiers that must match this service definition.
* @param Instance type.
* @return An instance of the contract or impl along with other information. May return null if there is no provider that
* provides the given implementation or contract.
*/
List> getAllServiceHolders(Class contractOrImpl, Annotation... qualifiers);
/**
* Gets the best service from this injection manager that implements this contract or has this implementation.
*
* Use this method only if other information is not needed otherwise use, otherwise use
* {@link InjectionManager#getAllServiceHolders(Class, Annotation...)}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param qualifiers The set of qualifiers that must match this service definition.
* @param Instance type.
* @return An instance of the contract or impl. May return null if there is no provider that provides the given
* implementation or contract.
*/
T getInstance(Class contractOrImpl, Annotation... qualifiers);
/**
* Gets the best service from this injection manager that implements this contract or has this implementation.
*
* Use this method only if other information is not needed otherwise use, otherwise use
* {@link InjectionManager#getAllServiceHolders(Class, Annotation...)}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param classAnalyzer -------
* @param Instance type.
* @return An instance of the contract or impl. May return null if there is no provider that provides the given
* implementation or contract.
*/
// TODO: Remove CLASS ANALYZER - NEEDED ONLY IN CdiComponentProvider
T getInstance(Class contractOrImpl, String classAnalyzer);
/**
* Gets the best service from this injection manager that implements this contract or has this implementation.
*
* Use this method only if other information is not needed otherwise use, otherwise use
* {@link InjectionManager#getAllServiceHolders(Class, Annotation...)}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param Instance type.
* @return An instance of the contract or impl. May return null if there is no provider that provides the given
* implementation or contract.
*/
T getInstance(Class contractOrImpl);
/**
* Gets the best service from this injection manager that implements this contract or has this implementation.
*
* Use this method only if other information is not needed otherwise use, otherwise use
* {@link InjectionManager#getAllServiceHolders(Class, Annotation...)}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param Instance type.
* @return An instance of the contract or impl. May return null if there is no provider that provides the given
* implementation or contract.
*/
T getInstance(Type contractOrImpl);
/**
* Gets the service instance according to {@link ForeignDescriptor} which is specific to the underlying DI provider.
*
* @param foreignDescriptor DI specific descriptor.
* @return service instance according to foreign descriptor.
*/
Object getInstance(ForeignDescriptor foreignDescriptor);
/**
* Creates and registers the descriptor in the underlying DI provider and returns {@link ForeignDescriptor} that is specific
* descriptor for the underlying DI provider.
*
* @param binding org.testifyproject descriptor.
* @return specific foreign descriptor of the underlying DI provider.
*/
ForeignDescriptor createForeignDescriptor(Binding binding);
/**
* Gets all services from this injection manager that implement this contract or have this implementation.
*
* Use this method only if other information is not needed otherwise use, otherwise use
* {@link InjectionManager#getAllServiceHolders(Class, Annotation...)}.
*
* @param contractOrImpl May not be null, and is the contract or concrete implementation to get the best instance of.
* @param Instance type.
* @return A list of services implementing this contract or concrete implementation. May not return null, but may return
* an empty list
*/
List getAllInstances(Type contractOrImpl);
/**
* Analyzes the given object and inject into its fields and methods.
* The object injected in this way will not be managed by HK2
*
* @param injectMe The object to be analyzed and injected into
*/
void inject(Object injectMe);
/**
* This will analyze the given object and inject into its fields and methods. The object injected in this way will not be
* managed by HK2
*
* @param injectMe The object to be analyzed and injected into
*/
// TODO: Remove CLASS ANALYZER - only in legacy CDI integration.
void inject(Object injectMe, String classAnalyzer);
/**
* Analyzes the given object and call the preDestroy method. The object given will not be managed by bean manager.
*
* @param preDestroyMe The object to preDestroy
*/
void preDestroy(Object preDestroyMe);
}