net.java.truecommons.annotations.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of truecommons-annotations Show documentation
Provides common annotations with processors. You should use the scope "provided" when adding this module as a dependency.
The newest version!
/*
 * Copyright (C) 2005-2015 Schlichtherle IT Services.
 * All rights reserved. Use is subject to license terms.
 */
/**
 * Provides annotations for
 * {@linkplain net.java.truecommons.annotations.ServiceSpecification service specifications}
 * and
 * {@linkplain net.java.truecommons.annotations.ServiceImplementation service implementations}.
 * Using these annotations saves you from the tedious and error-prone process
 * of manually editing service provider configuration files in
 * {@code META-INF/services}
 * and enables some design-time error checking for your service specifications
 * and implementations in your IDE.
 *
 * The {@code @ServiceImplementation} Annotation
 * 
 * Suppose you wanted to implement a service provider for location by the
 * {@link java.util.ServiceLoader} class.
 * Using the {@code @ServiceImplementation} annotation, your implementation
 * could then look similar to this:
 * 

 * package com.company.project;
 *
 * import java.nio.charset.spi.CharsetProvider;
 * import net.java.truecommons.services.annotations.ServiceImplementation;
 *
 * @ServiceImplementation(CharsetProvider.class)
 * public class Ibm437CharsetProvider extends CharsetProvider {
 *     ...
 * }
 * 
 * 
 * The
 * {@linkplain net.java.truecommons.annotations.processing.ServiceImplementationProcessor processor}
 * associated with the {@code @ServiceImplementation} annotation will then
 * generate the service provider configuration file
 * {@code META-INF/services/java.nio.charset.spi.CharsetProvider}
 * and place the service provider class name
 * {@code com.company.project.Ibm437CharsetProvider} into it.
 * 

 * The annotation processor performs some static code analysis in order to
 * detect any obvious errors and emits appropriate error messages,
 * e.g. if the implementation class is non-public or abstract
 * or if there is no public constructor with zero parameters available.
 * 

 * If your IDE performs annotation processing, then any error messages should
 * get highlighted in the editor at design-time.
 * Furthermore, if your IDE supports refactoring, then changing the class name
 * of the implementation automatically updates the entry in the service
 * provider configuration file.
 *
 * 
The {@code @ServiceSpecification} Annotation
 * 
 * Suppose you wanted to design your own specification class or interface.
 * Using the {@code @ServiceSpecification} annotation, your specification
 * could then look similar to this:
 * 

 * package com.company.project.spec;
 *
 * import net.java.truecommons.services.annotations.ServiceSpecification;
 *
 * @ServiceSpecification
 * public interface UltimateServiceSpecification {
 *     ...
 * }
 * 
 * 
 * The
 * {@linkplain net.java.truecommons.annotations.processing.ServiceSpecificationProcessor processor}
 * associated with the {@code @ServiceSpecification} annotation will then
 * perform some static code analysis to detect any obvious errors and emit
 * appropriate error messages, e.g. if the specification class or interface is
 * non-public or final or if there is no public or protected constructor with
 * zero parameters available.
 * 

 * An implementation of your specification could then look like this:
 * 

 * package com.company.project.impl;
 *
 * import com.company.project.spec.UltimateServiceSpecification;
 * import net.java.truecommons.services.annotations.ServiceSpecification;
 *
 * @ServiceImplementation
 * public class UltimateServiceImplementation
 * implements UltimateServiceSpecification {
 *     ...
 * }
 * 
 * 
 * Note that the {@code @ServiceImplementation} annotation does not specify any
 * implemented classes or interfaces.
 * The annotation processor associated with the {@code @ServiceImplementation}
 * annotation will then scan the type hierarchy of the annotated class for any
 * superclass or interface which is annotated with the
 * {@code @ServiceSpecification} annotation and generate the service provider
 * configuration files according to its findings.
 * If no specification class or interface is found then an appropriate error
 * message gets emitted.
 *
 * @see    java.util.ServiceLoader
 * @see    JAR File Specification for Java SE 6, Section "Service Provider"
 * @since  TrueCommons 2.1
 * @author Christian Schlichtherle
 */
@javax.annotation.Nonnull @javax.annotation.ParametersAreNonnullByDefault
package net.java.truecommons.annotations;