package com.codiform.moo;
import java.util.Collection;
import java.util.List;
import java.util.Set;
import com.codiform.moo.configuration.Configuration;
import com.codiform.moo.curry.Translate;
import com.codiform.moo.curry.Update;
import com.codiform.moo.property.source.CompositeSourcePropertyFactory;
import com.codiform.moo.session.TranslationSession;
import com.codiform.moo.session.TranslationSource;
import com.codiform.moo.translator.CachingTranslatorFactory;
/**
* Central facade class for interacting with Moo to do mapping from objects to objects. Much of the
* capability of the framework can be exercised at this level without ever delving into many of the
* classes within.
*
* <p>
* Also serves as a long-term cache for anything that can be cached between invocations, things that
* aren't session-specific, although these caches survive only as long as your instance of Moo,
* which might be almost exactly as long as the session in many cases.
* </p>
*
* <p>
* Alternately, you might find working directly with {@link Translate} and {@link Update} more to
* your taste.
* </p>
*
* <p>
* Some simple examples of Moo in action:
* <p>
* <ul>
* <li>Moo.translate( UserDto.class ).from( currentUser );</li>
* <li>Moo.translate( UserDto.class ).fromEach( activeUsers );</li>
* <li>Moo.translate( currentUser, UserDto.class );</li>
* <li>Moo.translate( activeUsers, UserDto.class );</li>
* </ul>
*
* <p>
* Moo supports a limited amount of configuration through annotations, in particular
* {@link com.codiform.moo.annotation.Property}, {@link com.codiform.moo.annotation.MapProperty},
* {@link com.codiform.moo.annotation.CollectionProperty} and {@link com.codiform.moo.annotation.Ignore}
* </p>
*
* <p>
* Instances of Moo are intended to be typesafe, they can be used by more than one thread at once
* without an issue, and can be cached and re-used.
* </p>
*/
public class Moo {
private CachingTranslatorFactory translatorFactory;
private CompositeSourcePropertyFactory sourcePropertyFactory;
/**
* Creates a new instance of Moo with a default {@link Configuration}.
*/
public Moo() {
this( new Configuration() );
}
/**
* Creates a new instance of Moo with a known (and specified) {@link Configuration}.
*
* @param configuration
* the configuration for this instance of Moo
*/
public Moo( Configuration configuration ) {
this.sourcePropertyFactory = new CompositeSourcePropertyFactory();
this.translatorFactory = new CachingTranslatorFactory( configuration, sourcePropertyFactory );
}
/**
* Prepare for translation to a destination class by creating a 'curried' operation which can be
* invoked upon to do translations.
*
* @param <T>
* the type to which translations should be performed
* @param destinationClass
* the class for the type to which translations should be performed
* @return a class representing the 'curried' {@link Translate}
*/
public <T> Translate<T> translate( Class<T> destinationClass ) {
return new Translate<T>( translatorFactory, destinationClass );
}
/**
* Perform a translation of a source object into an instance of the destination class.
*
* @param <T>
* the type to which translation should take place
* @param source
* the object to be used as the source of the translation
* @param destinationClass
* the class of the type to which translation should take place
* @return the instance of the destination class with values translated from the source instance
*/
public <T> T translate( Object source, Class<T> destinationClass ) {
return newSession().getTranslation( source, destinationClass );
}
/**
* Perform a translation of a list of source objects into an list of instances of the
* destination class.
*
* @param <T>
* the type to which translation should take place
* @param sources
* the objects to be used as the sources of the translation
* @param destinationClass
* the class of the type to which translation should take place
* @return a list of instances of the destination class with values translated from the source
* instances
*/
public <T> List<T> translateEach( List<?> sources, Class<T> destinationClass ) {
return newSession().getEachTranslation( sources, destinationClass );
}
/**
* Perform a translation of a collection of source objects into an collection of instances of
* the destination class.
*
* @param <T>
* the type to which translation should take place
* @param sources
* the objects to be used as the sources of the translation
* @param destinationClass
* the class of the type to which translation should take place
* @return a collection of instances of the destination class with values translated from the
* source instances
*/
public <T> Collection<T> translateEach( Collection<?> sources, Class<T> destinationClass ) {
return newSession().getEachTranslation( sources, destinationClass );
}
/**
* Perform a translation of a set of source objects into an set of instances of the destination
* class.
*
* @param <T>
* the type to which translation should take place
* @param sources
* the objects to be used as the sources of the translation
* @param destinationClass
* the class of the type to which translation should take place
* @return a set of instances of the destination class with values translated from the source
* instances
*/
public <T> Set<T> translateEach( Set<?> sources, Class<T> destinationClass ) {
return newSession().getEachTranslation( sources, destinationClass );
}
/**
* Update the destination object with values from the source object.
*
* @param source
* the source object, from which properties will be read
* @param destination
* the destination object, to which properties will be written
*/
public void update( Object source, Object destination ) {
newSession().update( source, destination );
}
/**
* Create a curried update from a source object which could then be applied to several
* destination objects.
*
* @param source
* the source object, from which properties will be read
*/
public Update update( Object source ) {
return new Update( translatorFactory, source );
}
protected TranslationSource newSession() {
return new TranslationSession( translatorFactory );
}
}