io.neba.api.spi

Interface AnnotatedFieldMapper<FieldType,AnnotationType extends Annotation>

Type Parameters:

FieldType - the super type of the field type of the mapped type.

AnnotationType - the exact type of the annotation this mapper is responsible for.

public interface AnnotatedFieldMapper<FieldType,AnnotationType extends Annotation>

OSGi services implementing this interface may customize the mapping of arbitrary fields during the resource to model mapping of any resource model.

The implementing service specifies the annotation it is responsible for as well as the type the mapped fields must be assignable to.

For example, the following service would be responsible for fields annotated with @MyAnnotation with a type assignable to Collection, e.g. List<Resource> or Set<String>.

 @Component(service = { AnnotatedFieldMapper.class })
 public class MyFieldMapper implements AnnotatedFieldMapper<Collection, MyAnnotation> {
     public Class<? extends Collection> getFieldType() {
         return Collection.class;
     }

     public Class<Annotation> getAnnotationType() {
         return MyAnnotation.class;
     }

     public Collection map(OngoingMapping<Collection, MyAnnotation> ongoingMapping) {
         ...
     }
 }
 

Custom mappers are always invoked after all of NEBA's standard mappings have occurred, but before the corresponding value was set on the model's field. They may thus make use of the already resolved value or choose to provide a different one.

It is crucial for a AnnotatedFieldMapper to always return a value that is assignment compatible to the field type, i.e. either of the same or of a more specific type. It is insufficient to return a type compatible to the mapping methods return type declaration. This return type only represents the type any returned value must be compatible to.
For instance, if a mapper is responsible for Collection, it must take care to return the field's actual collection type, e.g. List or Set. Otherwise, an exception will arise.

Implementations must never store any contextual data provided by the AnnotatedFieldMapper.OngoingMapping as this data stems from arbitrary OSGi bundles with independent life cycles. Storing any data would result in a class loader / memory leak when these bundles change.

Since:

1.0.0

Author:

Olaf Otto

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	AnnotatedFieldMapper.OngoingMapping<FieldType,AnnotationType> Represents the contextual data of a field mapping during a resource to model mapping.

Method Summary

Modifier and Type	Method and Description
Class<AnnotationType>	getAnnotationType()
Class<? super FieldType>	getFieldType()
FieldType	map(AnnotatedFieldMapper.OngoingMapping<FieldType,AnnotationType> ongoingMapping)

Method Detail

getFieldType

@Nonnull
Class<? super FieldType> getFieldType()

Returns:

never null.

getAnnotationType

@Nonnull
Class<AnnotationType> getAnnotationType()

Returns:

never null.

map

@CheckForNull
FieldType map(AnnotatedFieldMapper.OngoingMapping<FieldType,AnnotationType> ongoingMapping)

Parameters:

ongoingMapping - never null.

Returns:

The value to be set on the mapped field during the resource to model mapping. Must return a value that is assignment-compatible to AnnotatedFieldMapper.OngoingMapping.getFieldType(). Can be null.