Download Download View Ubiquity on GitHub

Welcome to Ubiquity

Ubiquity is a utility framework used to copy objects into other objects that may not be compatible.

Why ubiquity ?

  • Ubiquity is fast When some other popular tools (like beanutils or dozer) use reflexion, Ubiquity parses the bytecode of classes and generates copiers on the fly. Thus, the code wil call "new" to create objets and use getters and setters directly. Since it doesn't use reflexion, it is dramatically faster, you can expect your copy times to be divided by 10 !! The tests I made showed Ubiquity is about 3 times faster than Orika, and about 20 times faster than Dozer. If you have tests showing different resuls, feel free to send me them.
  • Ubiquity performs recursive deep copy, and will go as deep as possible
  • Support different logging systems, you choose the one you want
  • Ubiquity only needs asm to work, nothing more ! All other dependencies are optionnal, and not needed unless you use them.

Getting ubiquity

You can get ubiquity with this link : https://github.com/downloads/larochef/ubiquity/ubiquity-1.0-rc5.jar If ubiquity grows enough in popularity, I will do my best for it to be on maven central !

Getting started

Using ubiquity is as simple as :

Ubiquity ubiquity = new Ubiquity();
MyObject1 myObject1 = new MyOject1();
// populate and have fun with your object
MyObject2 myObject2 = ubiquity.map(myObject1, MyObject2.class);

Configuration : working with collections and maps

Framework support

Ubiquity support copying collections and maps, as long as you respect a few rules :

  • List and maps should be declared by their interface
  • Lists and maps must be parametrized

The different types of collections supported are :

java.util.Collection
java.util.List
java.util.Set
java.util.Map

Configuring the implementations of collections

To specify your favorite implementations of collections, all you have to do is to provide your Ubiquity with a CollectionFactory.

package org.ubiquity;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * Factory for the different kinds of common collections.
 * Implementing this interface allows you to choose the implementations.
 *
 * Date: 24/04/12
 *
 * @author François LAROCHE
 */
public interface CollectionFactory {

    /**
     * Create a new List
     * @param <T>  the type of objects that can be added to the list
     * @return a new list, for objects of type T
     */
    <T> List <T> newList();

    /**
     * Create a new set
     * @param <T>  the type of objects that can be added to the set
     * @return a new set, for objects of type T
     */
    <T> Set<T> newSet();

    /**
     * Creates a new map
     *
     * @param <K> the type associated to the keys
     * @param <T> the type associated to the objects
     * @return a new map
     */
    <K,T> Map<K,T> newMap();

    /**
     * Default collection creation
     * @param <T> the type of elments to store in the collection
     * @return a new Collection for objects of type T
     */
    <T>Collection<T> newCollection();
}

Defaults are :

  • java.util.ArrayList for java.util.List or java.util.Collection
  • java.util.HashSet for java.util.Set
  • java.util.HashMap for java.util.Map

Dealing with special cases

There will be cases when all that's provided will not be enough. These cases can be, for exemple, converting from an enum to another one, or dealing with other special objects. For all these special cases, you can tell Ubiquity how to copy a class to another one. All you have to do is create a copier implementing org.ubiquity.Copier, or you can extend, if it meets your need the org.ubiquity.bytecode.SimpleCopier class. Then, you can simply define it :

ubiquity.setCopier(SrcClass.class, DestinationClass.class, myCopier);

Then, any copy done by this ubiquity object from SrcClass to DestinationClass will use this copier.

Property matching

By default, every getter or setter will be taken into account, which means that a read-only property can be copier into a write only property ! Properties are matched by name.

Ignoring a property

If you want to have a property no copied, just annote it with 

@org.ubiquity.annotation.CopyIgnore

Renaming a property

Ubiquity supports renaming properties and also allow multiple renaming configuration according to the target object class. When multiple configurations exist, Ubiquity will, at first, try to match a renaming for the target class. If none exist, it will take the default configuration (which will be with no target class, or java.lang.Object). If no configuration is found, then the property isn't renamed.

@org.ubiquity.annotation.CopyRename(propertyName="property2")
public String getProperty1() {...}

@org.ubiquity.annotation.CopyRenames(configurations={
@org.ubiquity.annotation.CopyRename(propertyName="property2"),
@org.ubiquity.annotation.CopyRename(propertyName="property3", targetClass=DestinationClass.class)
}
public String getProperty1() {...}

At the moment, you cannot rename to a nested property, which means,

@org.ubiquity.annotation.CopyRename(propertyName="property2.property3")
public String getProperty1() {...}

will throw an Exeption.

Support or Contact

Please have fun with it ! If you have any trouble, please use all the feedback tools to let me know. François LAROCHE