Package global.namespace.service.wight.annotation

Provides annotations for service interface and service implementations.

See: Description

Annotation Types Summary

Annotation Type	Description
ServiceImplementation	Indicates that the annotated type is an implementation of a locatable service.
ServiceInterface	Indicates that the annotated type is the interface of a locatable service.

Package global.namespace.service.wight.annotation Description

Provides annotations for service interface and service implementations. Using these annotations saves you from the tedious and error-prone task of manually editing service provider configuration files in META-INF/services and enables some design-time error checking for your service interfaces and implementations in your IDE.

The @ServiceImplementation Annotation

Suppose you wanted to implement a service provider for location by the ServiceLoader class. Using the @ServiceImplementation annotation, your implementation could then look similar to this:

 package com.company.project;

 import java.nio.charset.spi.CharsetProvider;
 import net.java.truecommons3.services.annotations.ServiceImplementation;

 @ServiceImplementation(CharsetProvider.class)
 public class Ibm437CharsetProvider extends CharsetProvider {
     ...
 }
 

The processor associated with the @ServiceImplementation annotation then generates the service provider configuration file META-INF/services/java.nio.charset.spi.CharsetProvider and places the service provider class name 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 @ServiceInterface Annotation

Suppose you wanted to design your own service interface. Using the @ServiceInterface annotation, your service interface could then look like this:

 package com.company.project.api;

 import net.java.truecommons3.services.annotations.ServiceInterface;

 @ServiceInterface
 public interface UltimateServiceInterface {
     ...
 }
 

The processor associated with the @ServiceInterface annotation then performs some static code analysis to detect any obvious errors and emits appropriate error messages, e.g. if the interface type is non-public or final or if there is no public or protected constructor with zero parameters available.

Your service implementation could then look like this:

 package com.company.project.impl;

 import com.company.project.api.UltimateServiceInterface;
 import net.java.truecommons3.services.annotations.ServiceImplementation;

 @ServiceImplementation
 public class UltimateServiceImplementation
 implements UltimateServiceInterface {
     ...
 }
 

Note that the @ServiceImplementation annotation does not specify any implemented classes or interfaces. The annotation processor associated with the @ServiceImplementation annotation scans the type hierarchy of the annotated class for any superclass or interface which is annotated with the @ServiceInterface annotation and generates the service provider configuration files according to its findings. If no service interface is found then an appropriate error message is emitted.

Author:

Christian Schlichtherle

See Also:

ServiceLoader, JAR File Specification for Java SE 6, Section "Service Provider"