org.eclipse.sisu.space.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of standalone-sisu-uber Show documentation
There is a newer version: 3.0.0-alpha-3
/*
 * Copyright (c) 2010-2024 Sonatype, Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * 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;