When converting to or from a Java type, the key is derived from the method or field name. Certain common property name characters, such as full stop ('.' \u002E) and hyphen-minus ('-' \u002D) are not valid in Java identifiers. So the name of a method must be converted to its corresponding key name as follows:

Table 707.5 contains some name mapping examples.

Below is an example of using the PREFIX_ constant in an annotation. The example receives an untyped Dictionary in the updated() callback with configuration information. Each key in the dictionary is prefixed with the PREFIX_. The annotation can be used to read the configuration using typed methods with short names.

  public @interface MyAnnotation {
    static final String PREFIX_ = "com.acme.config.";

    long timeout() default 1000L;
    String tempdir() default "/tmp";
    int retries() default 10;
  }
  
  public void updated(Dictionary dict) {
    // dict contains:
    // "com.acme.config.timeout" = "500"
    // "com.acme.config.tempdir" = "/temp"
    
    MyAnnotation cfg = converter.convert(dict).to(MyAnnotation.class);
    
    long configuredTimeout = cfg.timeout(); // 500
    int configuredRetries = cfg.retries(); // 10
    
    // ...
  }

However, if the type is a single-element annotation, see 9.7.3 in [1] The Java Language Specification, Java SE 8 Edition, then the key name for the value method is derived from the name of the component property type rather than the name of the method. In this case, the simple name of the component property type, that is, the name of the class without any package name or outer class name, if the component property type is an inner class, must be converted to the value method's property name as follows:

Table 707.6 contains some mapping examples for the value method.

When converting to a Map a separate instance is returned that can be owned by the caller. By default the result is created eagerly and populated with converted content.

When converting to a java.util.Map the converter can produce a live view over the backing object that changes when the backing object changes. The live view can be enabled by specifying the view() modifier.

In all cases the object returned is a separate instance that can be owned by the client. When the client modifies the returned object a live view will stop reflecting changes to the backing object.

When converting from a map-like object to a Map or sub-type, each key-value pair in the source map is converted to desired types of the target map using the generic information if available. Map type information for the target type can be made available by using the to(TypeReference) or to(Type) methods. If no type information is available, key-value pairs are used in the map as-is.

Converting between a map and a Dictionary is done by iterating over the source and inserting the key value pairs in the target, converting them to the requested target type, if known. As with other generic types, target type information for Dictionaries can be provided via a TypeReference.

Converting a map-like structure into an interface can be a useful way to give a map of untyped data a typed API. The converter synthesizes an interface instance to represent the conversion.

Note that converting to annotations provides similar functionality with the added benefit of being able to specify default values in the annotation code.

interface Config {
  int my_value(); // no default
  int my_value(int defVal);
  int my_value(String defVal); // String value is automatically converted to int
  boolean my_other_value();
}

// Usage
Map<String, Object> myMap = new HashMap<>(); // an example map
myMap.put("my.other.value", "true");
Config cfg = converter.convert(myMap).to(Config.class);
int val = cfg.my_value(17); // if not set then use 17
boolean val2 = cfg.my_other_value(); // val2=true

Map m = converter.convert(myMultiInterface).
      sourceAs(MyInterfaceB.class).to(Map.class);

Conversion to and from annotations behaves similar to interface conversion with the added capability of specifying a default in the annotation definition.

When converting to an annotation type, the converter will return an instance of the requested annotation class. As with interfaces, values are only obtained from the conversion source when the annotation method is actually called. If the requested value is not available, the default as specified in the annotation class is used. If no default is specified a ConversionException is thrown.

Similar to interfaces, conversions to and from annotations also follow the Key Mapping for annotation element names. Below a few examples of conversions to an annotation:

@interface MyAnnotation {
  String[] args() default {"arg1", "arg2"};
}

// Will set sa={"args1", "arg2"}
String[] sa = converter.convert(new HashMap()).to(MyAnnotation.class).args();

// Will set a={"x", "y", "z"}
Map m = Collections.singletonMap("args", new String [] {"x", "y", "z"});
String[] a = converter.convert(m).to(MyAnnotation.class).args();

// Will set a1={}
Map m1 = Collections.singletonMap("args", null)
String[] a1 = converter.convert(m1).to(MyAnnotation.class).args();

// Will set a2={""}
Map m2 = Collections.singletonMap("args", "")
String[] a2 = converter.convert(m2).to(MyAnnotation.class).args();

// Will set a3={","}
Map m3 = Collections.singletonMap("args", ",")
String[] a3 = converter.convert(m3).to(MyAnnotation.class).args();

Java Beans are concrete (non-abstract) classes that follow the Java Bean naming convention. They provide public getters and setters to access their properties and have a public no-parameter constructor. When converting from a Java Bean introspection is used to find the read accessors. A read accessor must have no arguments and a non-void return value. The method name must start with get followed by a capitalized property name, for example getSize() provides access to the property size. For boolean/Boolean properties a prefix of is is also permitted. Properties names follow the Key Mapping.

For the converter to consider an object as a Java Bean the sourceAsBean() or targetAsBean() modifier needs to be invoked, for example:

  Map m = converter.convert(myBean).sourceAsBean().to(Map.class);

When converting to a Java Bean, the bean is constructed eagerly. All available properties are set in the bean using the bean's write accessors, that is, public setters methods with a single argument. All methods of the bean class itself and its super classes are considered. When a property cannot be converted this will cause a ConversionException. If a property is missing in the source, the property will not be set in the bean.

Note: access via indexed bean properties is not supported.

Note: the getClass() method of the java.lang.Object class is not considered an accessor.

DTOs are classes with public non-static fields and no methods other than the ones provided by the java.lang.Object class. OSGi DTOs extend the org.osgi.dto.DTO class, however objects following the DTO rules that do not extend the DTO class are also treated as DTOs by the converter. DTOs may have static fields, or non-public instance fields. These are ignored by the converter.

When converting from a DTO to another map-like structure each public instance field is considered. The field name is taken as the key for the map entry, taking into account Key Mapping, the field value is taken as the value for the map entry.

When converting to a DTO, the converter attempts to find fields that match the key of each entry in the source map and then converts the value to the field type before assigning it. The key of the map entries may need to be converted into a String first. Keys are mapped according to Key Mapping.

The DTO is constructed using its no-parameter constructor and each public field is filled with data from the source eagerly. Fields present in the DTO but missing in the source object not be set.

The converter only considers a type to be a DTO type if it declares no methods. However, if a type needs to be treated as a DTO that has methods, the converter can be instructed to do this using the sourceAsDTO() and targetAsDTO() modifiers.

The converter uses reflection to find a public java.util.Map getProperties() or java.util.Dictionary getProperties() method on the source type to obtain a map view over the source object. This map view is used to convert the source object to a map-like structure.

If the source object both implements an interface and also has a public getProperties() method, the converter uses the getProperties() method to obtain the map view. This getProperties() may or may not be part of an implemented interface.

Note: this mechanism can only be used to convert to another type. The reverse is not supported

The converter always produces an instance of the target type as specified with the to(Class), to(TypeReference) or to(Type) method. In some cases the converter needs to be instructed how to treat this target object. For example the desired target type might extend a DTO class adding some methods and behavior to the DTO. As this target class now has methods, the converter will not recognize it as a DTO. The targetAs(Class), targetAsBean() and targetAsDTO() methods can be used here to instruct the converter to treat the target object as certain type of object to guide the conversion.

For example:

  MyExtendedDTO med = converter.convert(someMap).
      targetAsDTO().to(MyExtendedDTO.class)

In this example the converter will return a MyExtendedDTO instance but it will treat is as a MyDTO type.