com.amazon.carbonado.adapter

Annotation Type AdapterDefinition

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface AdapterDefinition

Allows annotations to be defined for supporting property types which are not natively supported by the underlying storage layer. Repositories must always attempt to match property types to the best matching native type, but they may have to rely on an adapter to make a conversion.

The annotation is just a pointer to an adapter implementation class. If the adapter class is not explicitly provided, it defaults to a static inner class named "Adapter" in the annotation itself.

The adapter class must have a public constructor that accepts the annotation that has the AdapterDefinition annotation. It must also define several adapt methods which convert property values. An adapt method needs to start with "adapt", accept one parameter and return something.

Example true/false adapter for booleans:

 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 @AdapterDefinition
 public @interface TrueFalseAdapter {

     public static class Adapter {
         private final String propertyName;

         // Constructor may throw a MalformedTypeException if
         // params supplied by annotation are illegal.

         /**
          * @param type optional type of object that contains the adapted property
          * @param propertyName name of property with adapter
          * @param annotation specific annotation that binds to this adapter class
          */
         public Adapter(Class type, String propertyName, TrueFalseAdapter annotation) {
             this.propertyName = propertyName;
         }

         // Define at least two adapt methods for each supported property type.

         /**
          * @param propertyValue value to convert from
          */
         public char adaptToChar(boolean propertyValue) {
             return value ? 'T' : 'F';
         }

         /**
          * @param propertyValue value to convert from
          */
         public boolean adaptToBoolean(char propertyValue) {
             if (propertyValue == 'T') { return true; };
             if (propertyValue == 'F') { return false; };
             throw new IllegalArgumentException
                 ("Cannot adapt '" + value + "' into boolean for property \"" +
                   propertyName + '"');
         }
     }
 }
 

The newly defined adapter can be applied to property accessors.

 public interface UserInfo extends Storable {
     @TrueFalseAdapter
     boolean isAdministrator();
     void setAdministrator(boolean admin);
 }
 

Author:

Brian S O'Neill

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.Class	implementation Specify class which will perform property adaptation.
java.lang.Class[]	storageTypePreferences Optionally specify the set of preferred storage types for storing the adapted property, in order of most preferred to least preferred.

Element Detail

implementation

public abstract java.lang.Class implementation

Specify class which will perform property adaptation. Must have a public constructor with the signature (Class type, String propertyName, Annotation), where Annotation refers to the annotation with the adapter definition.

The implementation class need not be explicitly specified. By default, the adapter class must be a static inner class of the annotation, named "Adapter".

Default:

void.class

storageTypePreferences

public abstract java.lang.Class[] storageTypePreferences

Optionally specify the set of preferred storage types for storing the adapted property, in order of most preferred to least preferred. A type in the set must be supported by the adapt methods to be considered.

If the repository is independent, it needs help on deciding exactly how to store the adapted property. A dependent repository will not have as much flexibility in selecting an appropriate type, but it may still need a hint.

Default:

{}