org.eclipse.sisu.space.package-info Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2010-present Sonatype, Inc.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Stuart McCulloch (Sonatype, Inc.) - initial API and implementation
*******************************************************************************/
/**
* Customizable scanning of bean implementations.
*
* The {@link org.eclipse.sisu.space.SpaceModule} should be given a {@link org.eclipse.sisu.space.ClassSpace} representing the classes and resources to scan:
*
*
* Guice.createInjector( new SpaceModule( new URLClassSpace( classloader ) ) );
*
* Reduce scanning time by using an {@link org.eclipse.sisu.space.SisuIndex index} or provide your own {@link org.eclipse.sisu.space.ClassFinder} approach:
*
*
* Guice.createInjector( new SpaceModule( new URLClassSpace( classloader ), BeanScanning.INDEX ) );
*
* The default visitor strategy is to use {@link org.eclipse.sisu.space.QualifiedTypeVisitor} with {@link org.eclipse.sisu.space.QualifiedTypeBinder} to find types annotated with {@code @Named} or other {@code @Qualifier}s and bind them as follows:
*
* Components
* Any qualified components are bound using a special "wildcard" key that the {@link org.eclipse.sisu.inject.BeanLocator} uses to check type compatibility at lookup time:
*
* (This avoids the need to walk the type hierarchy and register bindings for each and every super-type, turning the injector graph to spaghetti.)
*
*
* @Named("example") public class MyTypeImpl implements MyType {
* // ...
* }
* If you use an empty {@code @Named} or a different {@code @Qualifier} annotation then Sisu will pick a canonical name based on the implementation type.
*
*
* Sometimes you need explicit typed bindings for external integration; you can list the types in a {@code @Typed} annotation or leave it empty to use the declared interfaces:
*
*
* @Named @Typed public class MyTypeImpl implements MyType {
* // ...
* }
*
* Default implementations can be indicated by using "default" as a binding name:
*
*
* @Named("default") public class MyTypeImpl implements MyType {
* // ...
* }
*
* or by starting the implementation name with "Default":
*
*
* @Named public class DefaultMyType implements MyType {
* // ...
* }
*
* Default components are bound without a qualifier and have a higher ranking than non-default components.
*
* Providers
* Any qualified providers are bound using the same binding heuristics as components:
*
*
* @Named public class MyProvider implements Provider<MyType> {
* public MyType get() {
* // ...
* }
* }
* Use {@code @Singleton} to scope the provided binding(s) as a singleton:
*
*
* @Named @Singleton public class MyProvider implements Provider<MyType> {
* public MyType get() {
* // ...
* }
* }
* Note: this is different to the normal Guice behaviour where singleton only applies to the provider itself.
*
* Modules
* Any qualified modules are are installed using the current binder:
*
*
* @Named public class MyModule extends AbstractModule {
* @Override protected void configure() {
* // ...
* }
* }
*
* Mediators
* Any qualified {@link org.eclipse.sisu.Mediator}s are registered with the {@link org.eclipse.sisu.inject.BeanLocator}:
*
*
* @Named public class MyMediator implements Mediator<Named, MyType, MyWatcher> {
* public void add( BeanEntry<Named, MyType> entry, MyWatcher watcher ) throws Exception {
* // ...
* }
*
* public void remove( BeanEntry<Named, MyType> entry, MyWatcher watcher ) throws Exception {
* // ...
* }
* }
*/
package org.eclipse.sisu.space;