org.interstellarocean.terraforming.reflection.package-info Maven / Gradle / Ivy

Go to download
/*
 * Copyright © 2015 The Authors
 *
 * https://www.gnu.org/licenses/lgpl-3.0-standalone.html
 */
/**
 * Support for model transformers using reflection libraries.
 * Model transforming using reflection shall be considered a supplementary technology, where the usual use of data structures' accessors and mutators
 * (or fields access) is most robust and is the preferred way to implement model transforming.
 * Implementors are discouraged from using reflection transforming library's advanced configurations and techniques as these are frequently not robust,
 * not portable between libraries, and may lead to bugs that are hard to track.
 * All fields that cannot be transformed by simple reflection shall be just excluded from reflection transforming and transformed
 * by the base model transformer instead.
 * And don't forget to write tests for your model transformers regardless it uses reflection or not.
 *
 * References
 * 
 * Java Bean Mapping is wrong,
 * 		let's fix it! @javatronic.fr
 * 
Dozer vs Orika vs Manual @sokolenko.me
 * 
Java Object to Object Mapper @javacodegeeks
 * 
 *
 * Description
 * Set of interfaces allowing clean separation of {@link org.interstellarocean.terraforming.ModelTransformer}s code
 * from external reflection transforming libraries.
 * 
 * {@link org.interstellarocean.terraforming.ModelTransformer} implementors should follow the guidelines:
 * 
 *
 * 
 *
 * 
 * {@link org.interstellarocean.terraforming.ModelTransformer} should use
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformerFactory}'s factory and strategy patterns
 * to obtain and use requested library provider's {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformer} builder.
 * The factory's builder method invocation should be parameterized with requested types of transformer to be build.
 * 
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformerProvider} interface provides a builder allowing
 * creation and configuration of {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformer} instances in a library-independent way.
 * The provider implementation should isolate the library allowing easy change of used library
 * in {@link org.interstellarocean.terraforming.ModelTransformer} implementations.
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformer} instances built by the provider implementation must be thread-safe.
 * 
 * 
 *
 * 
 * {@link org.interstellarocean.terraforming.ModelTransformer} should use obtained
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformerBuilder} to actually create and configure
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformer} instance.
 * Instances returned by the builder are thread-safe.
 * 
 *
 * 
 * {@link org.interstellarocean.terraforming.ModelTransformer} should use built
 * {@link org.interstellarocean.terraforming.reflection.ReflectionModelTransformer} instance to perform actual reflection transforming.
 * 
 *
 * 
 *
 * Example
 *
 *  * public class FooToDtoModelTransformer implements ToDtoModelTransformer<FooDomain, FooDto> {
 *
 * 	// This is the only contact with actual reflection transforming library. Easy to change if needed!
 * 	private static final Class<?> FOO_LIBRARY = org.bar.Foo.class;
 *
 * 	private final ReflectionModelTransformerFactory reflectionModelTransformerFactory;
 *
 * 	private ReflectionModelTransformer<FooDomain, FooDto> toDtoReflectionModelTransformer;
 *
 * 	@Inject // @Autowired, etc.
 * 	public FooToDtoModelTransformer(ReflectionModelTransformerFactory reflectionModelTransformerFactory) {
 * 		this.reflectionModelTransformerFactory = reflectionModelTransformerFactory;
 * 	}
 *
 * 	@PostConstruct
 * 	void buildReflectionModelTransformer() {
 * 		ReflectionModelTransformerBuilder<FooDomain, FooDto> builder = reflectionModelTransformerFactory.getBuilderFor(FOO_LIBRARY);
 * 		toDtoReflectionModelTransformer = builder
 * 				.from(FooDomain.class)
 * 				.to(FooDto.class)
 * 				.excludeFields(emptyList())
 * 				.build();
 * 	}
 *
 * 	@Override
 * 	public FooDto toDto(FooDomain domain) {
 * 		return toDtoReflectionModelTransformer.from(domain).to(new FooDto());
 * 	}
 *
 * }
 * 
 *
 * @see org.interstellarocean.terraforming.ModelTransformer
 * @see org.interstellarocean.terraforming.reflection.ReflectionModelTransformerFactory
 * @see org.interstellarocean.terraforming.reflection.ReflectionModelTransformerBuilder
 * @see org.interstellarocean.terraforming.reflection.ReflectionModelTransformerProvider
 * @see org.interstellarocean.terraforming.reflection.ReflectionModelTransformer
 *
 * @author Dariusz Wakuliński
 */
package org.interstellarocean.terraforming.reflection;