Table of Contents Installation ............................................................................................................................................... 3 3rd Party Dependencies ...................................................................................................................... 3 Tutorial .................................................................................................................................................... 4 Setup the mapping factory ................................................................................................................. 4 Reference ............................................................................................................................................. 5 Auto mapping ...................................................................................................................................... 5 Custom Mapper .................................................................................................................................. 6 Converter ............................................................................................................................................. 7 Mapping fields with different name .................................................................................................. 8 Customize the default field-name mapping ...................................................................................... 8 Nested property ................................................................................................................................... 9 Collections.......................................................................................................................................... 10 Bi-directional mapping ..................................................................................................................... 10 Primitives ........................................................................................................................................... 10 Immutable Types .............................................................................................................................. 10 Enumerations .................................................................................................................................... 11 Inheritance ......................................................................................................................................... 11 Generic Types .................................................................................................................................... 11 Object factories ................................................................................................................................. 13 Proxy Instances ................................................................................................................................. 13 Debugging Generated Mappers, Converters, etc. .............................................................................. 14 Pre-requisites...................................................................................................................................... 14 Edit Source Lookup Path ................................................................................................................... 14 Security Exception for Eclipse jar signing ........................................................................................ 15 Generate Source and/or Class Files .................................................................................................. 15 Summary................................................................................................................................................ 17 FAQs ...................................................................................................................................................... 18 Should I write unit tests to confirm that Orika mapped my objects successfully? ..................... 18 What types of data objects are supported?..................................................................................... 18

Will Orika convert data types? ........................................................................................................ 18 How does Orika handle immutable types? ..................................................................................... 18 Does Orika automatically map fields with the same property name? ......................................... 18 Is the default mapping behavior configurable?.............................................................................. 19 Will Orika map recursively?............................................................................................................ 19 How does Orika perform the actual mapping? .............................................................................. 19 Are Collections and Arrays and Maps supported? ........................................................................ 19 Is class inheritance supported? ........................................................................................................ 19 Are generics supported? ................................................................................................................... 19 Can Orika map to interfaces and abstract types?.......................................................................... 19 How is Orika mapping configured? ................................................................................................ 20 Can Orika be used with Spring? ..................................................................................................... 20 When do I need to explicitly register mapping for 2 types? .......................................................... 20 Is an explicitly registered mapping definition bi-directional, or do I need to define it in both directions?.......................................................................................................................................... 20 What if I want some of the mappings require different definitions in each direction? .............. 20 How can I tell what Orika is doing at runtime? (Which mappers are registered, how did it resolve my request to a particular mapper/converter/etc., when and how did it auto-generate a mapping?) .......................................................................................................................................... 20 Which version JDK versions are supported? ................................................................................. 20 Is Orika available in the maven-central repository? ..................................................................... 21 Can I map an object contained in a collection or map to a field, or vise-versa? ......................... 21 Can I map fields that don't have corresponding getter/setter methods, or call non-public constructors? ..................................................................................................................................... 21 Are Enum types supported?............................................................................................................. 21 When mapping generic Collections or Maps how do I tell Orika the values of the template parameters? ....................................................................................................................................... 21 I have a mapping case not supported by Orika--what are my options? ...................................... 21 What is the difference between a Mapper, ObjectFactory, and Converter? ............................... 22 How can I debug Orika? .................................................................................................................. 22 Can I use the EclipseJdt compiler strategy in production? .......................................................... 22

Installation For maven users, the easiest way to get going is to add the following dependency to your project. Please verify the latest version: ma.glasnost.orika orika-core 1.2.0

If you do not use maven please download the latest version of the archive zip with dependencies and put it on your classpath. Once your project is configured you can begin the following tutorial.

3rd Party Dependencies Orika use javassist to generate byte-code dynamically. If you're downloading and installing the compiled jar in your local m2 repository rather than building from source using maven, you will not get any of the transitive dependencies

Tutorial Setup the mapping factory The get an instance of MapperFacade initialise a MapperFactory: MapperFactory factory = new DefaultMapperFactory.Builder().build(); factory.registerClassMap(factory.classMap(Order.class,OrderDTO.class) .field("product.state.type.label", "stateLabel") .field("product.name", "productName").toClassMap()); MapperFacade mapper = factory.getMapperFacade();

Alternative Configuration/Setup Option (since 1.1.2): Extend ma.glasnost.orika.impl.ConfigurableMapper, overriding the configure(MapperFactory mapperFactory) method to register any class-maps, converters, etc. Since ConfigurableMapper implements MapperFacade, you can then simply construct a new instance (or have one injected) of your extension class and use it as a mapper (your custom configure method will be called during initialization). public class MyCustomMapper extends ConfigurableMapper { @Override public void configure(MapperFactory mapperFactory) { // register class maps, Mappers, ObjectFactories, and Converters ... mapperFactory.registerClassMap(...) mapperFactory.getConverterFactory().registerConverter(...) ... } @Override public void configureFactoryBuilder(DefaultMapperFactory.Builder builder) { // configure properties of the factory, if needed } } public class SomeOtherClass { private MapperFacade mapper = new MyCustomMapper(); void someMethod() { mapper.map(blah, Blah.class); ... } ... }

This method works particularly well with Spring; just wire up your extension class as a singleton

Reference In this example we will show you how to map from a class A to another class B and vice versa. Let’s have a look at our domain model: Product (A) Source : public class Product { private String productName; private String productDescription; private Double price; private Boolean availability; // getters & setters }

ProductDto (B) Destination : public class ProductDto { private String productName; private String description; private BigDecimal price; private Boolean availability; // getters & setters }

Note that we have explicitly chosen different and alike attributes names and types.

Auto mapping Map from Product to ProductDto Result (Orika-AutoMapping) : Orika will automatically find all attributes with the same name and type and map them. NB: Remember that, when declaring a custom mapper and/or a converter, you are overriding the Orika auto-mapping functionality temporarily; applying the byDefault() method to the ClassMapBuilder will apply default auto-mapping behvaior to the remaining properties. This allows you to do any of the following: 1. map all properties automatically // register the auto-mapping function mapperFactory.registerClassMap(mapperFactory.classMap(Product.class,ProductDto. class).byDefault().toClassMap());

2. explicitly specify every property mapping mapperFactory.registerClassMap(mapperFactory.classMap(Order.class,OrderDTO.clas s) .field("product.state.type.label", "stateLabel") .field("product.name", "productName").toClassMap());

3. customize some properties, and accept automatic behavior for the rest mapperFactory.registerClassMap(mapperFactory.classMap(Order.class,OrderDTO.clas s) .field("product.state.type.label", "stateLabel") .field("product.name", "productName") .byDefault().toClassMap());

Custom Mapper Let’s take now a closer look at our Dto: The description field in our case has nothing to do with the former one from the product class, this field is now a set of information collected from other fields, let’s say that the description should look something like this: Description example: The Dreamcast is a fabulous product which only cost 150 Description in java: "The " + product.getProductName() +" is a fabulous product which only cost " + product.getPrice()

For specific field we have specific treatment, in this case we will create and register a custom mapper : // register your custom mapper ClassMapBuilder builder = mapperFactory.classMap(ProductDto.class, Product.class); builder.customize(new CustomMapper() { // create your custom mapper @Override public void mapBtoA( Product b, ProductDto a, MappingContext context) { a.setDescription("The " + b.getProductName() + " is a fabulous product which only cost " + b.getPrice()); }}); mapperFactory.registerClassMap(builder.byDefault().toClassMap());

Note that an instance of the current MapperFacade is available within your CustomMapper class as the protected field mapperFacade.

Converter Let’s move now to the price, in our case we want to format the price: 

Price in our product class is a Double  Price in our Dto class is a BigDecimal For this case we need to create a converter: // register your converter mapperFactory.getConverterFactory().registerConverter(new Converter() { public BigDecimal convert(Double source, Type destinationType) { return new BigDecimal(source); } public boolean canConvert(Type sourceType, Type destinationType) { return Double.class.equals(sourceType.getRawType()) && BigDecimal.class.equals(destinationType.getRawType()); } });

In this example our converter was anonymous, and Orika use the converter's canConvert to check if it can be used for a given mapping. For this kind of simple type conversion, Orika provides a less verbose solution. You can just subclass the builtin CustomConverter: // register your converter mapperFactory.getConverterFactory().registerConverter(new CustomConverter() { public BigDecimal convert(Double source, Type destinationClass) { return new BigDecimal(source); } });

In some cases you may want to be more specific about when a converter is applied; you can specify a converter at field mapping scope To use a field mapping scoped converter, the converter is registered with a string identifier; you can then specify that converter by id when declaring a field-mapping. ConverterFactory converterFactory = factory.getConverterFactory(); converterFactory.registerConverter("dateConverter1", new DateToStringConverter("dd/MM/yyyy")); converterFactory.registerConverter("dateConverter2", new DateToStringConverter("dd-MMyyyy")); factory.registerClassMap(factory.classMap(A.class, B.class).fieldMap("date").converter("dateConverter1").add().toClassMap()); factory.registerClassMap(factory.classMap(A.class, C.class).fieldMap("date").converter("dateConverter2").add().toClassMap());

In the last snippet, two converters are registered using two identifiers: ("dateConverter1" and "dateConverter2") and are specified on two different field mappings.

In the case of a two-way mapping, it is necessary to use a bidirectional converter. (In the previous example the DateToStringConverter is built-in bidirectional converter).

Mapping fields with different name Is an easy task--just point out the name of the attribute in class A and the supposed match in class B; keep in mind that the mapped attributes should be of an automatically-convertible type, otherwise you'll need to register a converter. mapperFactory.registerClassMap( mapperFactory.classMap(Product.class,ProductDto.class) .field("productDescription", "description") .byDefault() .toClassMap() );

Customize the default field-name mapping In some cases, you may have a particular pattern that applies to the attributes to be mapped; or you might have some special property name mappings which are common to your whole object graph. You can avoid declaring multiple explicit class (and field) mappings (if you wish) by registering a DefaultFieldMapper on the MapperFactory. For example, suppose all of the properties on a class A have names like "name", "title", "age", etc., but the corresponding properties on another class B have names like "myName", "myTitle", "myAge", etc. DefaultFieldMapper myDefaultMapper = new DefaultFieldMapper() { public String suggestMapping(String propertyName, Type fromPropertyType) { if(propertyName.startsWith("my")) { // Remove the "my" prefix and adjust camel-case return propertyName.substring(2,1).toLowerCase() + propertyName.substring(3); } else { // Add a "my" prefix and adjust camel-case return "my" + propertyName.substring(0,1).toUpperCase() + propertyName.substring(1); } } } mapperFactory.registerDefaultFieldMapper(myDefaultMapper );

By using this default field mapper, you could automatically map from A to B without any explicit class mapping declaration; or you could combine with your own explicit mappings for some fields in the usual manner. The DefaultFieldMappers registered are applied whenever the internal auto-mapping functionality is triggered, and are applied only after a direct one-to-one mapping for the attribute has failed. This means that if you have any attribute names which do match exactly, the hints would not override them; hints are used to provide extra 'guesses' when the name doesn't match.

You can also pass any hints you've defined (as var-args) into the byDefault() method when using ClassMapBuilder to build a class mapping; like so: MappingHint myHint = ... // same hint as defined above mapperFactory.registerClassMap( mapperFactory.classMap(A.class,B.class) .byDefault(myHint) .toClassMap() );

Nested property In some cases the class we’re mapping from is not a mirror of the one we’re mapping to. A nested property expression can be used to access attributes at different levels/depth. Example: public class Order { private Product product; // getter/setter } public class Product { private String productName; // getter/setter } public clsss OrderDTO { private String orderNum; // getter/setter }

Our Dto diagram contains a new attribute the orderNum which is in our case the product name. // register the nested property expression mapperFactory.registerClassMap( mapperFactory.classMap(Order.class,OrderDto.class) .field("product.productName", "orderNum") .byDefault() .toClassMap() );

Collections In reality an order contains a set of products: // register product and order mapperFactory.registerClassMap(mapperFactory.classMap(Product.class, ProductDto.class).field("productDescription", "description") .byDefault().toClassMap()); mapperFactory.registerClassMap(mapperFactory.classMap(Order.class, OrderDto.class).field("products", "productsDto").byDefault() .toClassMap());

You have guessed right, there is no special treatment for collections case, since it’s implicit, Orika will automatically detects the collection inside your source object and map it to the destination.

Bi-directional mapping Let’s have a look at our bi-directional domain, Our dto model : BookDto bookDto = mapperFacade.map(book, BookDto.class);

As you can see, nothing has changed, and of course the destination object will have bidirectional references as well.

Primitives Orika will map from primitives to their respective wrapper and vice versa automatically. Orika also automatically handles mappings for primitives (and their respective wrapper types) to and from java.lang.String whenever possible.

Immutable Types Orika has a built-in set of types it will treat as immutable (most of the primitive wrappers, String, etc.; the exact list (as of 1.1.9) is: Byte.class, Short.class, Integer.class, Long.class, Boolean.class, Character.class, Float.class, Double.class, String.class, BigDecimal.class, Date.class, java.sql.Date.class, Byte.TYPE, Short.TYPE, Integer.TYPE, Long.TYPE, Boolean.TYPE, Character.TYPE, Float.TYPE, Double.TYPE

To add your own types, just register a PassThroughConverter with any number of types you want to treat as immutable, like so: mapperFactory.getConverterFactory().registerConverter( new PassThroughConverter(MyType1.class, MyType2.class, MyType3.class));

You can pass in any number of Class or Type instances when constructing the PassThroughConverter; these types will then be "passed through" like immutable types instead of mapping their individual properties.

Enumerations Orika will map between instances of the same Enum automatically. Orika will also map from one Enum type to another so long as a matching instance name is found; if the appropriate mapping can't be determined by instance name, you can resolve this by registering a converter.

Inheritance Orika will auto-detect mappers defined for parent objects, and will attempt to reuse them in child class mappings. Orika will also attempt to use an existing mapping from a parent or interface if a mapper for a child cannot be created. This means that if you have a defined mapping for A to B, and Orika is asked to map A1 to B(where A1 extends A, but cannot mapped directly--such as when A1 is inaccessible to the current class-loader), Orika will use the declared mapping for A to B.

Generic Types As of version 1.1.0, all of the Orika map methods support type-specific versions which allow exact specification of the source type and destination type. These new method signatures use the special Type class to specify the generic information needed at runtime to exactly identify parameterized type(s). For example, suppose you have the following domain (getters/setters omitted): class Envelope private T contents; } class Container private T contained; } class Holder { private T held; } class Entry { private K key; private V value; }

And you'd like to map from instances of: Entry>, Envelope> to instances of:Entry, Container>:

This would not normally be possible with the Class-based methods, because there is not enough information available (at runtime, after java erasure) to determine the nested properties of the objects. But we can accomplish it by explicitly telling Orika both the source and target types to use: /* * Register the class-mapping as usual, using the Type instances instead * of Class values */ Type>, Envelope>> fromType = new TypeBuilder>, Envelope>>(){}.build(); Type, Container>> toType = new TypeBuilder, Container>>(){}.build(); mapperFactory.registerClassMap( mapperFactory.classMap(fromType, toType) .field("key.contained.held", "key.held") .field("value.contents.contained", "value.contained") .toClassMap()); /* * Map using the specific types */ Entry, Container> result = mapperFactory.getMapperFacade().map(fromObject, fromType, toType);

Note: this example is implemented in GenericsTestCase, for those looking at the source code Working with Type All of the new generics-supporting methods require using the custom ma.glasnost.orika.metadata.Type class to specify the actual generic types. Instances of Type can be obtained in 2 ways: 

Use the TypeBuilder, construct a new anonymous instance, and call the build() method on it, like so: Type> type = new TypeBuilder>(){}.build(); Type,E> type2 = new TypeBuilder,E>(){}.build();



Use one of the static TypeFactory methods, like so: /* * First argument is the raw type, following are 0..N parameter types, * which may be any instance of java.lang.reflect.Type, of which * ma.glasnost.orika.metadata.Type is also an instance. */ Type> type = TypeFactory.valueOf(A.class, B.class, C.class); Type,E> type2 = TypeFactory.valueOf(A.class, TypeFactory.valueOf(B.class, C.class, D.class), E.class);

Object factories In some cases we want to control how new object instances are created; in such cases we can define and register a custom ObjectFactory. Let’s take for instance a case where we have a Person with a default address that we want Orika to add automatically whenever facing a PersonDto. Let’s introduce the person domain’s model: Dto’s model : public class PersonFactory implements ObjectFactory { @Override public PersonDto create(Object source, Type destinationType) { PersonDto personDto = new PersonDto(); // set the default adress personDto.setAdressDto(new AdressDto("Morocco", "Casablanca")); return personDto; } }

Your factory must implement Orika’s ObjectFactory, with a suitable create() method which provides the custom instances. mapperFactory.registerObjectFactory(new PersonFactory(),PersonDto.class);

Don’t forget to register your Object factory. Orika is designed with the idea that the default behavior should be sufficient for most scenarios. It then offers customization points which can be used as needed to support what the defaults cannot.

Proxy Instances Orika will automatically handle proxy instances of java.lang.reflect.Proxy, as well as javassist and cglib style byte-code proxies. This handling is provided by using super-type resolution mechanism to find an accessible super-type (class or interface) from which to build a mapper. more specifics needed

Debugging Generated Mappers, Converters, etc. Pre-requisites If you're not getting the expected results out of Orika (or you want to contribute a fix or feature), you may wish to download the source and step through the mapping process to see the details. To enable step-through debugging into the generated objects (which Orika is building at runtime), you'll need to include the orika-eclipse-toolsmodule in your project, like so: ma.glasnost.orika orika-eclipse-tools 1.2.0

In addition, you'll also need to tell Orika you want to use Eclipse Jdt as the compiler strategy; there are 2 ways to do this, listed in order of precedence: 1. Use the DefaultMapperFactory.Builder MapperFactory factory = new DefaultMapperFactory.Builder() .compilerStrategy(new EclipseJdtCompilerStrategy()) .build(); // add mappers, hints, converters, etc...

2. Set the system property // Maybe more convenient, but sets at a global level... System.setProperty(OrikaSystemProperties.COMPILER_STRATEGY,EclipseJdtCompilerSt rategy.class.getName());

Edit Source Lookup Path If you're using Eclipse as your IDE, you may initially receive the "Source not found" window with a button labeled "Edit Source Lookup Path..." while trying to (debug) step into the source of a generated object. When you click this button, you'll need to add the location of the compiler output folder for your project as a File System Folder (not a Workspace Folder). This is due to the fact that source files will not actually exist until just before you're at the break-point and Eclipse will have a "stale" view of the workspace folder by that time. If you're using an IDE other than Eclipse, the procedure should be similar. Note that although Orika is leveraging the Eclipse Jdt to format and compile the code, it resolves these from it's own dependencies, so if using Maven, there should be few differences.

If your project follows the Maven folder structure, this folder would be the target/testclasses folder by default. Check your project configuration build path to see the target location if you're unsure. If not using Maven, you'll need to make sure the following Eclipse Jdt artifacts are added to the build path: jdt artifact

version

core

3.5.2

text

3.3.0

commands

3.3.0

runtime

3.3.100

osgi

3.3.0

common

3.3.0

jobs

3.3.0

registry

3.3.0

preferences

3.2.100

contenttype

3.2.100

Will other versions work (such as the latest from your own Eclipse IDE)? Probably...but we haven't confirmed this yet

Security Exception for Eclipse jar signing If you receive an exception like "'org.eclipse.core.runtime.ListenerList''s singing information doesn't match..., try moving the eclipse binaries to the front of the classpath; if you're using maven, just move the orika-eclipse-tools dependency before orika-core and you're done.

Generate Source and/or Class Files When using Javassist (the default) as the compiler strategy, Orika will not generate source or class files by default. When using Eclipse Jdt, Orika will generate source but not class files by default.

This behavior can be customized by setting some special system properties, like so: // Write out source files to (classpath:)/ma/glasnost/orika/generated/ System.setProperty(OrikaSystemProperties.WRITE_SOURCE_FILES,"true"); // Write out class files to (classpath:)/ma/glasnost/orika/generated/ System.setProperty(OrikaSystemProperties.WRITE_CLASS_FILES,"true");

Note that when using Javassist, the debug info is not being generated so you can look at the code, but you normally can't step into it during a debug session. You may also need to apply the auto-formatting feature of your favorite IDE to the Javassist strategy source as we're not really shooting for style points on these (normally in-memory only) classes. The Eclipse strategy generated files includes auto-formatting of the source and includes debug info so that you can step into the code during a debug session (as mentioned in the section above).

Summary Orika attempts to provide a relatively simple and painless means to map beans from one object graph to another, while also providing performance very close to coding by hand. It does this by generating and reusing byte-code for mappers, avoiding most of the extra processing that comes from relying on reflection. We're not attempting to discuss whether or not to use DTOs, or whether you should perform mapping between object graphs. We are going to illustrate some cases in which you may need to do this mapping, and where we hope Orika can help, such as: 

Multi layered applications  DDD you need for example a data mapper between bounded context Converting XML binding objects to UI beans

FAQs Should I write unit tests to confirm that Orika mapped my objects successfully? Of course! If you mapped these objects by hand, you would write a unit test, right? So you're just going to trust us that we mapped your objects the way you expected us to? That's giving Orika and it's authors a little too much credit. Please write tests to confirm the objects are mapped as you expect.

What types of data objects are supported? Orika uses reflection to access data object properties, and by default is designed to read object properties that conform to the JavaBeans standard. This means that an object with 'getName' and/or 'setName' methods would be said to have a property called 'name'; the 'setXXX' method is not required, and for (primitive) boolean return types, the 'getXXX' method can optionally be named 'isXXX' instead. Orika takes this a little bit further, including java.lang.Boolean types for the optional 'isXXX' naming, and Orika will also recognize public fields as properties to be used.

Will Orika convert data types? Yes. Most scenarios are supported by default, including primitives, primitive wrappers, Enums, Collections, Arrays, Maps, and Complex types. There are an additional set of converters for numeric and date types which can be enabled by calling the useBuiltinConverters(true) on DefaultMapperFactory.Builder. Additionally, it is straightforward to register a custom mapper (by extending ma.glasnost.orika.CustomMapper) to deal with a conversion that is not built-in.

How does Orika handle immutable types? Orika has a base set of types which it treats as immutable, i.e., that are copied by reference from the source to the destination. Specifically, that list includes all of the primitive types and their corresponding wrapper classes, String, BigDecimal, etc. User-defind/declared immutable types are possible via the registration of a special Converter (PassThroughConverter).

Does Orika automatically map fields with the same property name? Yes; when a mapping is requested for 2 types which have not been explicitly registered. When registering an explicit mapping from one type to another, Orika will do this only if the 'byDefault' method is called on the fluent-style ClassMapBuilder API.

Is the default mapping behavior configurable? Yes. Any number of DefaultFieldMapper instances can be defined/registered which are consulted for a default mapping, in the case where a matching field could not be found for a given property. Additionally, the default mapping behavior can be completely customized by extending ClassMapBuilder (see issue#33 ).

Will Orika map recursively? Yes. Orika will continue to map nested classes until mapping is completed with a "simple" type. It also contains fail-safes to properly deal with recursive references within the objects you're attempting to map.

How does Orika perform the actual mapping? Orika uses reflection to investigate the metadata of the objects to be mapped and then generates bytecode at runtime which is used to map those classes. This means that although some initial overhead is incurred to investigate the types and generate the mappers, the overall runtime performance is comparable to mapping by hand.

Are Collections and Arrays and Maps supported? Yes. Orika automatically maps between compatible multi-occurrence types (Arrays and java.util.Collection types, or between Map types) and automatically performs the necessary type conversions; mapping between Arrays, Collections, and Maps can be declared using the ClassMapBuilder API.

Is class inheritance supported? Yes. Orika will reuse mappers already defined for a given class hierarchy, and you can customize it using ClassMapBuilder.use

Are generics supported? Yes. Orika includes special runtime support for the mapping of generic types via a special Type class which can be used to define the exact type elements of a templated type.

Can Orika map to interfaces and abstract types? Yes. Orika has support for the registration of a "concrete" type for a given abstract/interface type, including a default registration for the common Map and Collection types.

How is Orika mapping configured? Orika mapping is configured via Java code at runtime, via a fluent-style ClassMapBuilder API. An instance is obtained from a MapperFactory which is then used to describe the mapping from one type to antoher. Finally, the specified ClassMap is registered with the MapperFactory for later use in generating a byte-code mapper. The recommended way to configure orika is by extendingma.glasnost.orika.impl.ConfigurableMapper, and providing any necessary customizations/configurations in the configure andconfigureFactoryBuilder methods; an instance of that custom mapper can then be safely shared as a singleton.

Can Orika be used with Spring? Yes. The best option is to define your own sub-class of ConfigurableMapper (as mentioned above) in singleton scope.

When do I need to explicitly register mapping for 2 types? Ideally, most of your field mappings can be performed automatically; for the exceptions, a custom mapping can be registered. Using an extension of ConfigurableMapper (as mentioned above), the configure() method is where this should be done.

Is an explicitly registered mapping definition bi-directional, or do I need to define it in both directions? Yes; registered (and automatically generated) mappings are bi-directional by default.

What if I want some of the mappings require different definitions in each direction? When defining a mapping, instead of using the field("fieldA","fieldB") method, use one of fieldAToB("fieldA","fieldB") orfieldBToA("fieldB","fieldA") to register a mapping in a single direction.

How can I tell what Orika is doing at runtime? (Which mappers are registered, how did it resolve my request to a particular mapper/converter/etc., when and how did it auto-generate a mapping?) Simply enable DEBUG logging for "ma.glasnost.orika" logger; Orika uses the Slf4J logging API, so should be compatible with most logging implementations if using an appropriate logging bridge.

Which version JDK versions are supported? 1.5 and above.

Is Orika available in the maven-central repository? Yes. ma.glasnost.orika orika-core 1.2.0

Can I map an object contained in a collection or map to a field, or vise-versa? Orika does not currently support this by default, but it can be achieved using a custom converter (by extendingma.glasnost.orika.CustomConverter or ma.glasnost.orika.converter.BidirectionalC onverter).

Can I map fields that don't have corresponding getter/setter methods, or call non-public constructors? Orika will allow mapping of public fields as properties, but otherwise, the mapping of inaccessible fields is not supported. Since Orika generates Java code to perform the actual mapping, it will generally follow the same restrictions of what you could write yourself.

Are Enum types supported? Yes. Enum instance are automatically mapped based on their instance values (when not of the same enumeration).

When mapping generic Collections or Maps how do I tell Orika the values of the template parameters? Use the ma.glasnost.orika.metadata.Type construct to pass the runtime type into a given map method.

I have a mapping case not supported by Orika--what are my options? Orika mappings can be customized by creating your own custom Converters, Mappers, and ObjectFactory types. See the question below for information on what the different constructs are used for and which you might need.

What is the difference between a Mapper, ObjectFactory, and Converter? 

A Mapper is used for applying the properties of an object of one type to an object of another type.



An ObjectFactory is used for constructing an instance of a particular destination type, in the context of mapping from a particular source type.



A Converter is used to completely take over the mapping process for a particular set of types.

How can I debug Orika? To show debug logging information about the mappings used, generated, and the types resolved, set the "ma.glasnost.orika" package to DEBUG logging level. To step-debug (in Eclipse or other IDE) into the actual generated classes, you'll first need to include the 'orika-eclipse-tools' jar in your project. ma.glasnost.orika orika-eclipse-tools 1.2.0 test

Note that Orika makes use of Eclipse JDT independent of any containing Eclipse runtime environment We recommend including this at 'test' scope if using Maven. Then, you can enable use of the EclipseJdtCompilerStrategy.class by setting the following system property value: -Dma.glasnost.orika.compilerStrategy=ma.glasnost.orika.impl.generator.EclipseJdtCompilerStrategy This will tell Orika to use EclipseJdt to compile and format the generated mapper objects with debug information which is necessary for step-debugging. Then, you'll need to add a File System folder to your debug source which includes your project's binary output location (if using Maven, this would be the 'target/classes' and 'target/test-classes' folders). Note that it cannot be a workspace reference, since the generated classes won't be known to Eclipse until after the test VM has been launched.

Can I use the EclipseJdt compiler strategy in production? Yes. The reason it is not the default has mostly to do with size and number of additional jars required. Runtime performance has been roughly equivalent to the Javassist strategy in tests thusfar, but you will want to disable the automatic writing of class and source files to disk by setting the following system properties (which default to 'true' in the EclipseJDt strategy): -Dma.glasnost.orika.writeSourceFiles=false -Dma.glasnost.orika.writeClassFiles=false

You will first need to make sure to include the 'orika-eclipse-tools' jar in your project's dependencies. ma.glasnost.orika orika-eclipse-tools 1.2.0

To enable/specify this compiler strategy, the best option is to specify it in the configureFactoryBuilder method of your extension ofConfigurableMapper, like so: public void configureFactoryBuilder(DefaultMapperFactory.Builder builder) { builder.compilerStrategy(new EclipseJdtCompilerStrategy()); }

A less-preferable option is to specify the system property (as mentioned in the above question about debugging Orika)

Table of Contents -

Does Orika automatically map fields with the same property name? ..... In this example our converter was anonymous, and Orika use the converter's canConvert .... For example, suppose you have the following domain (getters/setters omitted):.

610KB Sizes 16 Downloads 157 Views

Recommend Documents

Table of Contents
Feb 24, 2012 - Commission for Africa (ECA) [South African. Mission]. E-mail: [email protected] Mail: PO Box 1091, Addis Ababa, ETHIOPIA.

table of contents -
This component is installed locally in the PC or notebook of the CAMS2 subscriber. ... 9. You can choose the default extraction path or select a different path.

Table of Contents
Robots offer advantages not found in on-screen agents or technology embedded in ..... archive Proceedings of the 3rd ACM/IEEE international conference on.

Table of Contents
the actors in the problematic system to make theory a reality. .... example, associating Osama bin Laden's terrorist organization with Islam has proven to ...... 1992, Ramzi Yousef traveled from Peshawar to New York under a false name and Ali.

Table of Contents -
When do I need to explicitly register mapping for 2 types? ..... For example, suppose you have the following domain (getters/setters omitted): class Envelope.

table of contents
pleasant daily practice of responsible, purposeful decisions for developing ..... has sat out a minimum of one full semester. He may not return ..... Lunches, homework, books and other items may be left in the school ..... Updated: August 2018. 49.

table of contents
numerous notes providing additional information on the use of each material. 2. A tabulation of ...... API RP-520. 2.4.1. Determining Reaction Forces In An Open-Discharge System. The following formula is based on a condition of critical steady-state

Missionary Messages - Table of Contents - Swartzentrover.com
and are now calling for the missionary and his wife to visit their homes and teach them ..... did so, that "All power was given to Him both in heaven and in earth. ...... burning glass may be made of ice and may converge the solar rays to a flame.

TABLE OF CONTENTS Kindergarten.pdf
There was a problem loading more pages. Retrying... Whoops! There was a problem previewing this document. Retrying... Download. Connect more apps... Try one of the apps below to open or edit this item. TABLE OF CONTENTS Kindergarten.pdf. TABLE OF CON