Skip navigation links
TrueCommons 2.3.3

@Nonnull @ParametersAreNonnullByDefault

Package net.java.truecommons.annotations

Provides annotations for service specifications and service implementations.

See: Description

Package net.java.truecommons.annotations Description

Provides annotations for service specifications and service implementations. Using these annotations saves you from the tedious and error-prone process of manually editing service provider configuration files in META-INF/services and enables some design-time error checking for your service specifications 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.truecommons.services.annotations.ServiceImplementation;

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

The processor associated with the @ServiceImplementation annotation will then generate the service provider configuration file META-INF/services/java.nio.charset.spi.CharsetProvider and place 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 @ServiceSpecification Annotation

Suppose you wanted to design your own specification class or interface. Using the @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 processor associated with the @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 @ServiceImplementation annotation does not specify any implemented classes or interfaces. The annotation processor associated with the @ServiceImplementation annotation will then scan the type hierarchy of the annotated class for any superclass or interface which is annotated with the @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.

Since:
TrueCommons 2.1
Author:
Christian Schlichtherle
See Also:
ServiceLoader, JAR File Specification for Java SE 6, Section "Service Provider"
Skip navigation links
TrueCommons 2.3.3

Copyright © 2012–2017 Schlichtherle IT Services. All rights reserved.