Author: tchemit Date: 2009-01-16 18:49:43 +0000 (Fri, 16 Jan 2009) New Revision: 1307 Removed: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Gettor.java Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/BeanPropertyLoador.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Creator.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Deletor.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityListUpdator.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityLoador.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/ListUpdator.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Loador.java topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/TopiaEntityHelper.java Log: debut javadoc Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/BeanPropertyLoador.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/BeanPropertyLoador.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/BeanPropertyLoador.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -11,7 +11,15 @@ import java.util.List; import java.util.Map; -/** @author chemit */ +/** + * A implementation fo the {@link org.codelutin.topia.persistence.util.Loador} contract using + * {@link PropertyDescriptor}. + * <p/> + * Some factory methods are defined to simplify the generic cast, prefer used them + * instead of the (protected) constructor. + * + * @author chemit + */ public class BeanPropertyLoador<E> implements Loador<E> { public static <E> BeanPropertyLoador<E> newLoador(Class<E> klass, String... properties) { @@ -56,13 +64,14 @@ return descriptors; } + @Override public Map<String, Object> obtainProgperties(E from) { if (from == null) { return java.util.Collections.emptyMap(); } Map<String, Object> result = new HashMap<String, Object>(); for (PropertyDescriptor descriptor : getDescriptors()) { - Object read = null; + Object read; try { read = descriptor.getReadMethod().invoke(from); if (read != null) { Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Creator.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Creator.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Creator.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -2,7 +2,29 @@ import org.codelutin.topia.TopiaException; -/** @author chemit */ +/** + * A simple contract to hook the creation phase of an entity associated (or not!) to + * a parent entity. + * <p/> + * + * @author chemit + * @param <P> the type of the parent of the entity to create (if entity has + * no parent then used the {@link Void} type). + * @param <E> the type of entity to create + */ public interface Creator<P, E> { - E create(DBMapping mapping, P parent, E from) throws TopiaException; + /** + * Perform the creation of an entity. + * <p/> + * The given <code>from</code> entity should not have already been created in + * database ? it should only be here to prepare the creation of the entity. + * + * TODO Review this explanation :) + * + * @param parent the parent of the entity + * @param from the entity to create + * @return the really created entity in database + * @throws TopiaException if any db problem. + */ + E create(P parent, E from) throws TopiaException; } Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Deletor.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Deletor.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Deletor.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -1,6 +1,19 @@ package org.codelutin.topia.persistence.util; -/** @author chemit */ +/** + * A simple contract to hook the deletion of an entity. + * + * @author chemit + * @param <P> the parent of the entity to delete (if the entity has no parent says is not in a association + * of another entity, just used the {@link Void} type). + * @param <E> the type of the entity to delete. + */ public interface Deletor<P, E> { + /** + * Hook to delete an entity from a prent entity. + * + * @param parent the parent of the entity + * @param from the entity to delete. + */ void delete(P parent, E from); } Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityListUpdator.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityListUpdator.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityListUpdator.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -10,7 +10,14 @@ import java.lang.reflect.Method; import java.util.Collection; -/** @author chemit */ +/** + * A implementation of {@link ListUpdator} for {@link TopiaEntity} type. + * <p/> + * Some factory methods are defined to simplify the generic cast, prefer used them + * instead of the (protected) constructor. + * + * @author chemit + */ public class EntityListUpdator<P extends TopiaEntity, E extends TopiaEntity> implements ListUpdator<P, E> { public static <P extends TopiaEntity, E extends TopiaEntity> EntityListUpdator<P, E> newEntityListUpdator(Class<P> parentClass, Class<E> childClass, String propertyName) { Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityLoador.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityLoador.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/EntityLoador.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -2,7 +2,14 @@ import org.codelutin.topia.persistence.TopiaEntity; -/** @author chemit */ +/** + * A implementation of {@link BeanPropertyLoador} for {@link TopiaEntity} + * <p/> + * Some factory methods are defined to simplify the generic cast, prefer used them + * instead of the (protected) constructor). + * + * @author chemit + */ public class EntityLoador<E extends TopiaEntity> extends BeanPropertyLoador<E> { private static final long serialVersionUID = 1L; Deleted: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Gettor.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Gettor.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Gettor.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -1,6 +0,0 @@ -package org.codelutin.topia.persistence.util; - -/** @author chemit */ -public interface Gettor<P, E> { - E get(P parent, String topiaId); -} Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/ListUpdator.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/ListUpdator.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/ListUpdator.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -4,16 +4,59 @@ import java.util.Collection; -/** @author chemit */ +/** + * A simpel contract to allow you to update some collections of an entity. + * <p/> + * The purpose of the contract is to make possible (via a StorageService for example) some + * automatic and generic behaviour when you want to set a collection of childs into a entity. + * + * @author chemit + * @param <P> the type of the entity which contains the collection to update. + * @param <E> the type of entities in the collection. + */ public interface ListUpdator<P, E> { + /** + * Obtain a child from the entity given his id. + * + * @param parent the entity to query + * @param topiaId the id of the researched child entity. + * @return the child entity or <code>null</code>, if not found. + */ + E getChild(P parent, String topiaId); + /** + * Obtain the collection of childs from the entity. + * + * @param parent the entity to query. + * @return the collection of childs + */ Collection<E> getChilds(P parent); + /** + * Set the childs of an entity + * + * @param parent the entity to be setted + * @param childs the collection of childs to set. + */ void setChilds(P parent, Collection<E> childs); - void addToList(P parent, E bean) throws TopiaException; + /** + * Add a erntity to his parent + * + * @param parent the parent entity + * @param e the entity to add in parent. + * @throws TopiaException if any db problem while operation + */ + void addToList(P parent, E e) throws TopiaException; - void removeFromList(P parent, E bean) throws TopiaException; + /** + * Remove from a prent entity a given child. + * + * @param parent the parent entity + * @param e the child to remove. + * @throws TopiaException if any pb while operation. + */ + void removeFromList(P parent, E e) throws TopiaException; } Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Loador.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Loador.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/Loador.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -2,10 +2,32 @@ import java.util.Map; -/** @author chemit */ +/** + * A simple contract to load an entity from another one. + * + * @author chemit + */ public interface Loador<E> extends java.io.Serializable { - + /** + * Obtain from an entity all data to bind to another one according the definition of the loador. + * <p/> + * This method is usefull when you can not directly used the {@link #load(Object, Object, boolean)} method. + * <p/> + * For example, when an entity has a immutable business key (says with an hibernate naturalId for example), + * and that you want to create the data in a db, you must give all the properties at the create time so + * this method allow you to do it). + * + * @param from the entity to bind + * @return the map of properties to bind from the given entity. + */ Map<String, Object> obtainProgperties(E from); + /** + * Bind an entity to another. + * + * @param from the source entity + * @param dst the destination entity + * @param tech a flag to bind or not the technical values of the entity (says TopiaId, TopiaVersion and TopiaCreateDate). + */ void load(E from, E dst, boolean tech); } Modified: topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/TopiaEntityHelper.java =================================================================== --- topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/TopiaEntityHelper.java 2009-01-16 18:49:18 UTC (rev 1306) +++ topia/trunk/topia-persistence/src/main/java/org/codelutin/topia/persistence/util/TopiaEntityHelper.java 2009-01-16 18:49:43 UTC (rev 1307) @@ -64,7 +64,7 @@ } /** - * Récupère une entité dans une liste d'entité. + * Récupère une entité dans une liste d'entités. * * @param entities la liste des entités à scanner * @param topiaId l'id de l'entité recherchée