Author: athimel Date: 2012-05-25 16:15:39 +0200 (Fri, 25 May 2012) New Revision: 2533 Url: http://nuiton.org/repositories/revision/topia/2533 Log: Javadoc on TopiaDAO : not finished, I give up for the moment Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaUtil.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAO.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAOImpl.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/util/TopiaEntityHelper.java Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/TopiaContext.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -138,8 +138,8 @@ void removeTopiaEntityListener(TopiaEntityListener listener); /** - * Unregister the given TopiaEntityListener about he given entity class from - * the context + * Unregister the given TopiaEntityListener about the given entity class + * from the context * * @param entityClass the listened TopiaEntity's class * @param listener the listener instance to unregister @@ -181,8 +181,8 @@ void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable); /** - * Unregister the given TopiaEntityVetoable about he given entity class from - * the context + * Unregister the given TopiaEntityVetoable about the given entity class + * from the context * * @param entityClass the listened TopiaEntity's class * @param vetoable the vetoable instance to unregister Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaContextImpl.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -113,7 +113,6 @@ //TODO-fdesbois-20100507 : Need translation of javadoc. public class TopiaContextImpl implements TopiaContextImplementor { - /** to use log facility, just put in your code: log.info(\"...\"); */ private static final Log log = LogFactory.getLog(TopiaContextImpl.class); /** @@ -518,8 +517,8 @@ (Class<TopiaDAO<E>>) Class.forName(daoClassname); result = daoClass.getConstructor().newInstance(); } catch (Exception eee) { - log.warn("specialized DAO " + daoClassname + - " not found, use default TopiaDAOHibernate"); + log.warn("Specialized DAO " + daoClassname + + " not found, use default TopiaDAOImpl"); result = new TopiaDAOImpl<E>(); } Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaUtil.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaUtil.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaUtil.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -51,8 +51,7 @@ */ public class TopiaUtil { - /** to use log facility, just put in your code: log.info(\"...\"); */ - static private Log log = LogFactory.getLog(TopiaUtil.class); + private static final Log log = LogFactory.getLog(TopiaUtil.class); /** * Permet de récupérer le fichier de propriété ayant le nom passé en Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAO.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAO.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAO.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -69,8 +69,8 @@ TopiaEntityEnum getTopiaEntityEnum(); /** - * When TopiaContextImpl create the TopiaDAOHibernate, it must call this - * method just after. + * Method to invoke right after instance creation. It is done by the + * TopiaContext. * * @param context context * @param entityClass entity class @@ -89,14 +89,14 @@ E newInstance() throws TopiaException; /** - * Return class of entity managed by this DAO. + * Return the class of the entity managed by this DAO. * - * @return entity managed by this DAO + * @return this DAO's managed entity's class */ Class<E> getEntityClass(); /** - * Return context used by this DAO. + * Returns the context used by this DAO. * * @return Returns the context. */ @@ -108,7 +108,7 @@ * * @param type the type of entity to search * @param entity the entity - * @param <U> tthe type of entity to search + * @param <U> the type of entity to search * @return the list of entities of the given type which uses the given * entity * @throws TopiaException if any problem while getting data @@ -132,84 +132,106 @@ throws TopiaException; /** - * Retourne les permissions a verifier pour l'acces a l'entite pour le - * service Taas. + * Returns the persmissions to check before the enity access for the + * security service. * - * @param topiaId topiaId d'une entite - * @param actions encoded actions - * @return la liste des permissions + * @param entityId topiaId of the entity + * @param actions encoded actions + * @return the list of permissions * @throws TopiaException if any pb while getting datas */ - List<Permission> getRequestPermission(String topiaId, int actions) + List<Permission> getRequestPermission(String entityId, int actions) throws TopiaException; - /* Adders */ - + /** + * Registers a TopiaEntityListener about the managed entity class. + * <code>listener</code> instance will be notified AFTER any operation on + * the entity. + * + * @param listener the listener instance to register + * @see TopiaContext#addTopiaEntityListener(Class, TopiaEntityListener) + */ void addTopiaEntityListener(TopiaEntityListener listener); + /** + * Unregister the given TopiaEntityListener about the managed entity class. + * + * @param listener the listener instance to unregister + * @see TopiaContext#removeTopiaEntityListener(Class, TopiaEntityListener) + */ + void removeTopiaEntityListener(TopiaEntityListener listener); + + /** + * Register to the context a TopiaEntityVetoable about the managed entity + * class. <code>vetoable</code> instance will be notified BEFORE any + * operation on the entity. + * + * @param vetoable the vetoable instance to register + * @see TopiaContext#addTopiaEntityVetoable(Class, TopiaEntityVetoable) + */ void addTopiaEntityVetoable(TopiaEntityVetoable vetoable); - /* Removers */ - - void removeTopiaEntityListener(TopiaEntityListener listener); - + /** + * Unregister the given TopiaEntityVetoable about the managed entity class. + * + * @param vetoable the vetoable instance to unregister + * @see TopiaContext#removeTopiaEntityVetoable(Class, TopiaEntityVetoable) + */ void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable); /** - * Construit une nouvelle instance de l'objet géré par ce DAO + * Creates a new instance of the entity managed by the DAO * - * @param properties la liste des propriétés que doit avoir l'objet créé les - * arguments vont par paire (propertyName, value) - * @return un nouvel objet - * @throws TopiaException si un problème est rencontré durant - * l'instanciation - * @throws IllegalArgumentException Si le nombre on le type des arguments - * n'est pas bon ou que le type ou le nom - * d'une propriété est fausse + * @param properties the list of properties that the created entity will + * have. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the newly created entity + * @throws TopiaException if any problem during instantiation + * @throws IllegalArgumentException if the arguments count is not correct or + * if some property type is not the + * expected one + * @see #create(Map) */ E create(Object... properties) throws TopiaException; /** - * Construit une nouvelle instance de l'objet géré par ce DAO + * Creates a new instance of the entity managed by the DAO * - * @param properties la liste des propriétés que doit avoir l'objet créé - * @return un nouvel objet - * @throws TopiaException si un problème est rencontré durant - * l'instanciation - * @throws IllegalArgumentException Si le nombre on le type des arguments - * n'est pas bon ou que le type ou le nom - * d'une propriété est fausse + * @param properties the key-value list of properties that the created + * entity will have. + * @return the newly created entity + * @throws TopiaException if any problem during instantiation + * @throws IllegalArgumentException if some property type is not the + * expected one */ E create(Map<String, Object> properties) throws TopiaException; /** - * Permet de sauver un object instancié sans le DAO. - * Utilisé notement dans le cas ou le DAO est situé derriere une couche - * de webservice et que l'appel à la methode {@link #create(Object...)} - * serait trop couteux. + * Creates an entity not created without the DAO. Generally used when DAO + * is layered after a service layer where the {@link #create(Object...)} + * would be to onerous. * - * @param e l'entité instanciée à sauver - * @return l'entité avec son topiaID valorisé - * @throws TopiaException if any pb while creating datas + * @param e the instance to persist + * @return the persisted entity (with its topiaId valued) + * @throws TopiaException if any problem while creating data * @since 2.3.1 */ E create(E e) throws TopiaException; /** - * Permet d'ajouter ou de mettre a jour un objet. Cela permet d'ajouter par - * exemple un objet provenant d'un autre context mais du meme type de DAO. + * Update an entity. May be used for an entity coming from another context. * - * @param e l'entite a ajouter ou mettre a jour - * @return l'entity passé en paramètre. - * @throws TopiaException if any pb while updating datas + * @param e the entity to create or update + * @return the given entity + * @throws TopiaException if any problem while updating datas */ E update(E e) throws TopiaException; /** - * Permet de supprimer une entite. + * Removes the given entity from the storage * - * @param e l'entite a supprimer - * @throws TopiaException if any pb while deleting datas + * @param e the entity to remove + * @throws TopiaException if any problem while deleting datas */ void delete(E e) throws TopiaException; @@ -470,7 +492,7 @@ /** * Obtain from a given entity all objects which will be deleted if * entity is deleted (such objects are called composite). - * + * <p/> * <strong>Note:</strong> result is given as a Multimap indexed their type. * * @param entity entity to scan @@ -484,7 +506,7 @@ * Obtains from a given entity all objects used by this entity but will not * be removed when deleting given entity (such objects are called * aggregate). - * + * <p/> * <strong>Note:</strong> result is given as a Multimap indexed their type. * * @param entity entity to scan Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAOImpl.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAOImpl.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAOImpl.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -60,25 +60,20 @@ import java.util.Map; /** - * Cette classe permet d'avoir un ensemble de méthode implantée de façon - * standard et plus spécifiquement pour Hibernate. + * This class provides some methods in abstraction of JPA. This class is made to + * be overriden by each entity's DAO * <p/> - * Certains accès à Hibernate sont tout de même fait ici, car on a pris le choix - * de se baser entièrement sur hibernate pour la persistence, et il est ainsi - * possible d'accèder au meta information hibernate sur les classes lorque l'on - * en a besoin. + * Anyway, there is still some JPA access because we choose to be based only on + * JPA. * - * @param <E> le type de l'entite + * @param <E> the entity's type * @author bpoussin <poussin@codelutin.com> * @version $Id$ */ +public class TopiaDAOImpl<E extends TopiaEntity> implements TopiaDAO<E> { -public class TopiaDAOImpl<E extends TopiaEntity> implements - TopiaDAO<E> { // TopiaDAOImpl + private static final Log log = LogFactory.getLog(TopiaDAOImpl.class); - /** to use log facility, just put in your code: log.info(\"...\"); */ - private static Log log = LogFactory.getLog(TopiaDAOImpl.class); - protected Class<E> entityClass; protected TopiaContextImplementor context; @@ -95,12 +90,6 @@ "This method must be overided in generated DAO"); } - /** - * When TopiaContextImpl create the TopiaDAOHibernate, it must call this - * method just after. - * - * @param entityClass - */ @Override public void init(TopiaContextImplementor context, Class<E> entityClass) throws TopiaException { @@ -129,7 +118,7 @@ } catch (Exception e) { throw new TopiaException( "Impossible de trouver ou d'instancier la classe " - + implementation); + + implementation); } } @@ -148,7 +137,7 @@ } @Override - public List<Permission> getRequestPermission(String topiaId, int actions) + public List<Permission> getRequestPermission(String entityId, int actions) throws TopiaException { return null; } @@ -175,23 +164,7 @@ @Override public E create(E entity) throws TopiaException { - return create0(entity); -// // TODO EC-20100322 this code may be merged with other create() methods -// try { -// // first set topiaId -// String topiaId = TopiaId.create(entityClass); -// TopiaEntityAbstract entityAbstract = (TopiaEntityAbstract) entity; -// entityAbstract.setTopiaId(topiaId); -// entityAbstract.setTopiaContext(getContext()); -// -// // save entity -// getEntityManager().persist(entity); -// getContext().getFiresSupport().warnOnUpdateEntity(entity); -// return entity; -// } catch (PersistenceException eee) { -// throw new TopiaException(eee); -// } } @Override @@ -200,20 +173,20 @@ Object propertyName = null; Object value; try { - for (int i = 0; i < properties.length;) { + for (int i = 0; i < properties.length; ) { propertyName = properties[i++]; value = properties[i++]; map.put((String) propertyName, value); } } catch (ArrayIndexOutOfBoundsException eee) { throw new IllegalArgumentException("Wrong number of argument " - + properties.length - + ", you must have even number. Last property name read: " - + propertyName); + + properties.length + + ", you must have even number. Last property name read: " + + propertyName); } catch (ClassCastException eee) { throw new IllegalArgumentException( "Wrong argument type, wait property name as String and " + - "have " + propertyName.getClass().getName()); + "have " + propertyName.getClass().getName()); } E result = create(map); @@ -229,15 +202,9 @@ public E create(Map<String, Object> properties) throws TopiaException { E result = newInstance(); - // TODO reflechir s'il ne faudrait pas creer l'id avant l'event precedent - // reflechir toujours dans un context on les E pourrait ne pas - // etre des TopiaEntity (ce qui n'arrivera jamais vu la signature (TC)...) -// if (result instanceof TopiaEntity) { -// String topiaId = TopiaId.create(entityClass); TopiaEntityAbstract entity = (TopiaEntityAbstract) result; -// entity.setTopiaId(topiaId); entity.setTopiaContext(getContext()); -// } + try { for (Map.Entry<String, Object> e : properties.entrySet()) { String propertyName = e.getKey(); @@ -255,16 +222,10 @@ "Can't put properties on new Object", eee); } return create0(result); -// // on fait un save maintenant, car puisqu'on a creer l'entity au -// // travers du DAO, on s'attend a l'avoir a disposition tout de -// // suite pour les requetes sans avoir a faire un update dessus -// getEntityManager().persist(result); -// getContext().getFiresSupport().warnOnCreateEntity(result); -// return result; } protected E create0(E result) throws TopiaException { - // XXX AThimel 22/05/2012 Add it back here because it does not work in PrePersist event + String topiaId = TopiaIdUtil.create(entityClass); result.setTopiaId(topiaId); @@ -345,7 +306,6 @@ } @Override - @Deprecated public E findByQuery(TopiaQuery query) throws TopiaException { E result = query.executeToEntity(getContext(), getEntityClass()); return result; @@ -391,14 +351,12 @@ } @Override - @Deprecated public List<E> findAllByQuery(TopiaQuery query) throws TopiaException { List<E> results = query.executeToEntityList(getContext(), getEntityClass()); return results; } @Override - @Deprecated public Map<String, E> findAllMappedByQuery(TopiaQuery query) throws TopiaException { Map<String, E> results = @@ -407,13 +365,13 @@ } @Override - @Deprecated public <K> Map<K, E> findAllMappedByQuery(TopiaQuery query, String keyName, Class<K> keyClass) throws TopiaException { - Map<K, E> results = - query.executeToEntityMap(getContext(), getEntityClass(), - keyName, keyClass); + TopiaContextImplementor context = getContext(); + Class<E> entityClass = getEntityClass(); + Map<K, E> results = query.executeToEntityMap(context, entityClass, + keyName, keyClass); return results; } @@ -474,7 +432,6 @@ } @Override - @Deprecated public int countByQuery(TopiaQuery query) throws TopiaException { int result = query.executeCount(getContext()); return result; @@ -499,7 +456,7 @@ Map<String, Object> properties = new HashMap<String, Object>(); properties.put(propertyName, propertyValue); Object name = null; - for (int i = 0; i < others.length;) { + for (int i = 0; i < others.length; ) { try { name = others[i++]; propertyValue = others[i++]; @@ -507,13 +464,13 @@ } catch (ClassCastException eee) { throw new IllegalArgumentException( "Les noms des propriétés doivent être des chaines et " + - "non pas " + propertyName.getClass().getName(), + "non pas " + propertyName.getClass().getName(), eee); } catch (ArrayIndexOutOfBoundsException eee) { throw new IllegalArgumentException( "Le nombre d'argument n'est pas un nombre pair: " - + (others.length + 2) - + " La dernière propriété était: " + name, eee); + + (others.length + 2) + + " La dernière propriété était: " + name, eee); } } return properties; @@ -528,8 +485,8 @@ EntityType<E> meta = getClassMetadata(); // TODO AThimel 07/05/2012 See if it is possible to do it with EntityType // if (meta.hasNaturalIdentifier()) { - E result = findByProperties(keys); - return result; + E result = findByProperties(keys); + return result; // } } catch (PersistenceException eee) { throw new TopiaException(eee); @@ -551,13 +508,13 @@ // int[] ikeys = meta.getNaturalIdentifierProperties(); // String[] pnames = meta.getPropertyNames(); - Map<String, Object> keys = new HashMap<String, Object>(); + Map<String, Object> keys = new HashMap<String, Object>(); // for (int ikey : ikeys) { // keys.put(pnames[ikey], k[ikey]); // } - E result = findByProperties(keys); - return result; + E result = findByProperties(keys); + return result; // } } catch (PersistenceException eee) { throw new TopiaException(eee); @@ -568,24 +525,26 @@ } @Override - public Multimap<Class<? extends TopiaEntity>, TopiaEntity> getComposite(E entity) throws TopiaException { + public Multimap<Class<? extends TopiaEntity>, TopiaEntity> getComposite( + E entity) throws TopiaException { throw new UnsupportedOperationException( "This method must be overided in generated DAO"); } @Override - public Multimap<Class<? extends TopiaEntity>, TopiaEntity> getAggregate(E entity) throws TopiaException { + public Multimap<Class<? extends TopiaEntity>, TopiaEntity> getAggregate( + E entity) throws TopiaException { throw new UnsupportedOperationException( "This method must be overided in generated DAO"); } /** - * Renvoie l'EntityManager fournit par le context + * Returns the EntityManager provided by the context * * @return jpa session * @throws TopiaException if any pb */ - EntityManager getEntityManager() throws TopiaException { + protected EntityManager getEntityManager() throws TopiaException { return getContext().getEntityManager(); } @@ -608,7 +567,9 @@ return meta; } - protected Multimap<Class<? extends TopiaEntity>, TopiaEntity> fillComposite(Multimap<Class<? extends TopiaEntity>, TopiaEntity> tmp2) throws TopiaException { + protected Multimap<Class<? extends TopiaEntity>, TopiaEntity> fillComposite( + Multimap<Class<? extends TopiaEntity>, TopiaEntity> tmp2) + throws TopiaException { Multimap<Class<? extends TopiaEntity>, TopiaEntity> result = ArrayListMultimap.create(); @@ -623,7 +584,9 @@ return result; } - protected Multimap<Class<? extends TopiaEntity>, TopiaEntity> fillAggregate(Multimap<Class<? extends TopiaEntity>, TopiaEntity> tmp2) throws TopiaException { + protected Multimap<Class<? extends TopiaEntity>, TopiaEntity> fillAggregate( + Multimap<Class<? extends TopiaEntity>, TopiaEntity> tmp2) + throws TopiaException { Multimap<Class<? extends TopiaEntity>, TopiaEntity> result = ArrayListMultimap.create(); @@ -637,4 +600,5 @@ } return result; } + } //TopiaDAOImpl Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/util/TopiaEntityHelper.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/util/TopiaEntityHelper.java 2012-05-25 13:48:20 UTC (rev 2532) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/util/TopiaEntityHelper.java 2012-05-25 14:15:39 UTC (rev 2533) @@ -68,7 +68,6 @@ @Deprecated public class TopiaEntityHelper { - /** to use log facility, just put in your code: log.info(\"...\"); */ private static final Log log = LogFactory.getLog(TopiaEntityHelper.class); /** Le pattern d'une reference sur une association */