Author: athimel Date: 2013-07-20 01:32:02 +0200 (Sat, 20 Jul 2013) New Revision: 2775 Url: http://nuiton.org/projects/topia/repository/revisions/2775 Log: refs #552 Clean some APIs : mainly TopiaDAO and TopiaEntity (still not acheived, check out the TODOs Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/EntityVisitor.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/TopiaEntity.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntityEnum.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaIdFactory.java trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaPersistenceHelper.java Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/EntityVisitor.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/EntityVisitor.java 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/EntityVisitor.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -60,7 +60,9 @@ * @param type the type of the visited property * @param value the value of the visited property */ - void visit(TopiaEntity entity, String propertyName, Class<?> type, + void visit(TopiaEntity entity, + String propertyName, + Class<?> type, Object value); /** @@ -74,8 +76,11 @@ * @param type the type of the visited property * @param value the value of the visited property */ - void visit(TopiaEntity entity, String propertyName, - Class<?> collectionType, Class<?> type, Object value); + void visit(TopiaEntity entity, + String propertyName, + Class<?> collectionType, + Class<?> type, + Object value); /** * Visit a indexed value from a collection property for the given entity. @@ -89,8 +94,12 @@ * @param index the index of the visited property in his container * @param value the value of the visited property */ - void visit(TopiaEntity entity, String propertyName, - Class<?> collectionType, Class<?> type, int index, Object value); + void visit(TopiaEntity entity, + String propertyName, + Class<?> collectionType, + Class<?> type, + int index, + Object value); /** * Reset all states of the visitor. @@ -101,4 +110,5 @@ * This method should be invoked after usage of the visitor. */ void clear(); + } 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 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAO.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -77,60 +77,56 @@ E newInstance() 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éé 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 propertyNamesAndValues 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; + E create(Object... propertyNamesAndValues) 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; @@ -160,339 +156,367 @@ * Find an entity matching {@code value} for the given {@code propertyName}. * * @param propertyName property name to filter - * @param value value of the property to math + * @param value value of the property to match * @return the first entity matching the request - * @throws TopiaException + * @throws TopiaException if any pb while getting datas */ - E findByProperty(String propertyName, Object value) throws TopiaException; + E findByProperty(String propertyName, + Object value) throws TopiaException; /** - * @param propertyName le nom de la propriété - * @param value la valeur à tester - * @param others les autres proprietes doivent aller par 2 - * propertyName, value - * @return l'entité trouvé + * Find an entity matching a succession of propertyName + value arguments. + * + * @param propertyName the first property name to filter + * @param value the first value of the property to match + * @param propertyNamesAndValues other property names and values. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the first entity matching the request * @throws TopiaException if any pb while getting datas */ - E findByProperties(String propertyName, Object value, Object... others) throws TopiaException; + E findByProperties(String propertyName, + Object value, + Object... propertyNamesAndValues) throws TopiaException; /** * Find an entity matching {@code properties}. * - * @param properties les propriétés à matcher - * @return l'entité trouvé + * @param properties the properties key + value to match + * @return the first entity matching the request * @throws TopiaException if any pb while getting datas */ E findByProperties(Map<String, Object> properties) throws TopiaException; /** - * Execute une requête basé sur l'entité du DAO. Permet de récupérer une - * entité correspondant à la requête. + * Executes and returns the result (entity E) of the given HQL query string. * - * @param hql la requête hql à executer - * @param params les paramètres de la requète - * @return l'entité correspondant à la recherche ou null si aucune entité - * n'a été trouvée + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the entity E found or null * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ - E findByQuery(String hql, Object... params) throws TopiaException; + E findByQuery(String hql, + Object... propertyNamesAndValues) throws TopiaException; + // TODO AThimel 20/07/13 Add this method : E findByQuery(String hql, Map<String, Object> propertyNamesAndValues) throws TopiaException; + /** - * Execute une requête basé sur le {@code type} donné. - * <p/> - * Permet de récupérer une entité correspondant à la requête. + * Executes and returns the result (entity R) of the given HQL query string. * - * @param hql la requête hql à executer - * @param params les paramètres de la requète - * @return l'entité correspondant à la recherche ou null si aucune entité - * n'a été trouvée + * @param type the expected result type + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the entity R found or null * @throws TopiaException if any pb while getting datas + * @throws ClassCastException if the found type is not the expected one * @since 2.6.12 */ - <R> R findByQuery(Class<R> type, String hql, Object... params) throws TopiaException; + <R> R findByQuery(Class<R> type, + String hql, + Object... propertyNamesAndValues) throws TopiaException; + // TODO AThimel 20/07/13 Add this method : <R> R findByQuery(Class<R> type, String hql, Map<String, Object> propertyNamesAndValues) throws TopiaException; + /** - * Recherche la classe en utilisant la cle naturelle, chaque champs de la - * cle naturelle est une entre de la map passe en argument. + * Find an entity using the natural ids. Each field of the natural id has to be present in the given Map. * - * @param keys la liste des champs de la cle naturelle avec leur valeur - * @return l'entite trouvé + * @param keys Map with the natural id property name as Map.key, and value as Map.value + * @return the entity E found or null * @throws TopiaException if any pb while getting datas */ E findByPrimaryKey(Map<String, Object> keys) throws TopiaException; /** - * Recherche la classe en utilisant la cle naturelle, si la cle naturelle - * est composé de plusieurs champs alors les arguments passés doivent être - * dans l'ordre de declaration dans le fichier de mapping + * Find an entity using the natural ids. Each field of the natural id has to + * be present in the given Map. * - * @param k l'objet cle naturelle de la classe - * @return l'entité trouvé + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the entity E found or null * @throws TopiaException if any pb while getting datas */ - E findByPrimaryKey(Object... k) throws TopiaException; + E findByPrimaryKey(Object... propertyNamesAndValues) throws TopiaException; /** - * Récupère la première entité (du type géré par ce dao) dont la - * collection nommée {@code propertyName} contient la {@code property} - * donnée. + * Find the first entity which given collection (propertyName) contains the + * given value * - * @param propertyName le nom de la propriété - * @param property la propriété recherchée - * @return la première entité recherchée - * @throws TopiaException pour tout erreur lors de la recherche + * @param propertyName the name of the property (must be a collection) + * @param value the value to use for find + * @return the entity E found or null + * @throws TopiaException if any pb while getting datas * @since 2.5.4 */ - E findContains(String propertyName, Object property) throws TopiaException; + E findContains(String propertyName, + Object value) throws TopiaException; //------------------------------------------------------------------------// //-- findAllXXX methods --------------------------------------------------// //------------------------------------------------------------------------// /** - * Gets all entitys of the dao type in db. + * Finds all the entities managed by this DAO. * - * @return all entities of the dao type in db - * @throws TopiaException + * @return the full list of entities + * @throws TopiaException if any pb while getting datas */ List<E> findAll() throws TopiaException; /** - * Recuperation de tous les ids en base pour le type d'entite du dao. + * Finds all entites E managed by this DAO. The returned list will be ordered according to the given + * {@code propertyNames}. + * <p/> + * You can add on each {@code property} {@code ASC} or {@code DESC} to force the result order + * (by default is {@code ASC}). * - * @return la liste de tous les ids - * @throws TopiaException si pb en base + * @param propertyNames property names of order to apply + * @return all entities E of the dao entity type with given order + * @throws TopiaException if any pb while getting datas */ + List<E> findAllWithOrder(String... propertyNames) throws TopiaException; + + /** + * Find all the ids for the E entity type + * + * @return the full list of ids + * @throws TopiaException if any pb while getting datas + */ + // TODO AThimel 20/07/13 This method should return a Set ? List<String> findAllIds() throws TopiaException; /** - * Gets all entities of the dao type matching the {@code value} for the - * given {@code propertyName}. + * Finds all entities E which value for the given {@code propertyName} is + * {@code value} * - * @param propertyName property name to filter - * @param value value to match - * @return matching entities + * @param propertyName property name to use + * @param value value to expect + * @return the list of entities E having the given value * @throws TopiaException if any pb while getting datas */ - List<E> findAllByProperty(String propertyName, Object value) - throws TopiaException; + List<E> findAllByProperty(String propertyName, + Object value) throws TopiaException; /** - * Gets all entities of the dao type matching the {@code value} for the - * given {@code propertyName} and {@code others}. + * Finds all entities E matching the given {@code propertyName}, {@code value} + * AND all other properties * - * @param propertyName le nom de la propriété - * @param value la valeur à tester - * @param others les autres proprietes doivent aller par 2 - * propertyName, value - * @return matching entities + * @param propertyName property name to use + * @param value value to expect + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the list of entities E having the given value * @throws TopiaException if any pb while getting datas */ - List<E> findAllByProperties(String propertyName, Object value, - Object... others) throws TopiaException; + List<E> findAllByProperties(String propertyName, + Object value, + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets all entities of the dao type matching all the {@code properties}. + * Finds all entities E matching all the {@code properties} values. * * @param properties properties to match - * @return matching entities + * @return the list of entities E having the given values * @throws TopiaException if any pb while getting datas */ - List<E> findAllByProperties(Map<String, Object> properties) - throws TopiaException; + List<E> findAllByProperties(Map<String, Object> properties) throws TopiaException; /** - * Gets all entities when executing the given select query for the dao - * entity type. + * Finds all entities E when executing the given HQL query. * - * @param hql hql query - * @param params query params - * @return entites of the query result + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return the list of entities E found by the query and parameters * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ - List<E> findAllByQuery(String hql, Object... params) throws TopiaException; + List<E> findAllByQuery(String hql, + Object... propertyNamesAndValues) throws TopiaException; + // TODO AThimel 20/07/13 Add this method : List<E> findAllByQuery(String hql, Map<String, Object> propertyNamesAndValues) throws TopiaException; + /** * Gets all entities when executing the given select query for the given * {@code type} which may not be a entity type (int, long, map,...). * - * @param hql hql query - * @param params query params + * @param type the expected result type + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] * @return entites of the query result * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ <R> List<R> findAllByQuery(Class<R> type, String hql, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; + // TODO AThimel 20/07/13 Add this method : <R> List<R> findAllByQuery(Class<R> type, String hql, Map<String, Object> propertyNamesAndValues) throws TopiaException; + /** - * Gets all entities in lazy mode when executing the given select query + * Finds all entities E in lazy mode when executing the given select query * for the dao entity type. * <p/> - * <strong>Important note:</strong> + * <strong>Important note:</strong> // TODO AThimel 20/07/13 Write the important note... * - * @param hql hql query - * @param params query params - * @return entites of the query result + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites E of the query result * @throws TopiaException if any pb while getting datas * @since 2.6.14 */ Iterable<E> findAllLazyByQuery(String hql, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets all entities in lazy mode when executing the given select query + * Finds all entities R in lazy mode when executing the given select query * for the given {@code type} which may not be a entity type (int, long, map,...). * <p/> - * <strong>Important note:</strong> + * <strong>Important note:</strong> // TODO AThimel 20/07/13 Write the important note... * - * @param type type of data to return - * @param hql hql query - * @param params query params - * @return entites of the query result + * @param type the expected result type + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites R of the query result * @throws TopiaException if any pb while getting datas * @since 2.6.14 */ <R> Iterable<R> findAllLazyByQuery(Class<R> type, String hql, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets all entities in lazy mode when executing the given select query + * Finds all entities E in lazy mode when executing the given select query * for the dao entity type. * <p/> - * <strong>Important note:</strong> + * <strong>Important note:</strong> // TODO AThimel 20/07/13 Write the important note... * - * @param batchSize batch size - * @param hql hql query - * @param params query params - * @return entites of the query result + * @param batchSize batch size + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites E of the query result * @throws TopiaException if any pb while getting datas * @since 2.6.14 */ Iterable<E> findAllLazyByQuery(int batchSize, String hql, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets all entities in lazy mode when executing the given select query + * Finds all entities R in lazy mode when executing the given select query * for the given {@code type} which may not be a entity type (int, long, map,...). * <p/> - * <strong>Important note:</strong> + * <strong>Important note:</strong> // TODO AThimel 20/07/13 Write the important note... * - * @param type type of data to return - * @param batchSize batch size - * @param hql hql query - * @param params query params - * @return entites of the query result + * @param type the expected result type + * @param batchSize batch size + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites R of the query result * @throws TopiaException if any pb while getting datas * @since 2.6.14 */ <R> Iterable<R> findAllLazyByQuery(Class<R> type, int batchSize, String hql, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets a page of entities when executing the given select query for the dao + * Finds a page of entities E when executing the given select query for the dao * entity type (will only return the window of {@code startIndex - * endIndex} entities). + * // TODO AThimel 20/07/13 Reformulate(?) the "window thing" * - * @param hql hql query to execute - * @param startIndex first index of entity to return - * @param endIndex last index of entity to return - * @param params query params - * @return entites of the paginated query result + * @param hql the HQL query + * @param startIndex first index of entity to return + * @param endIndex last index of entity to return + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites E of the paginated query result * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ - <R> List<R> findAllByQueryWithBound(Class<R> type, - String hql, - int startIndex, - int endIndex, - Object... params) throws TopiaException; + List<E> findAllByQueryWithBound(String hql, + int startIndex, + int endIndex, + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets a page of entities when executing the given select query for the dao + * Finds a page of entities R when executing the given select query for the dao * entity type (will only return the window of {@code startIndex - * endIndex} entities). + * // TODO AThimel 20/07/13 Reformulate(?) the "window thing" * - * @param hql hql query to execute - * @param startIndex first index of entity to return - * @param endIndex last index of entity to return - * @param params query params - * @return entites of the paginated query result + * @param type the expected result type + * @param hql the HQL query + * @param startIndex first index of entity to return + * @param endIndex last index of entity to return + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entites R of the paginated query result * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ - List<E> findAllByQueryWithBound(String hql, - int startIndex, - int endIndex, - Object... params) throws TopiaException; + <R> List<R> findAllByQueryWithBound(Class<R> type, + String hql, + int startIndex, + int endIndex, + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets a page of entities of the given select {@code hql} query using the + * Gets a page of entities E of the given select {@code hql} query using the * {@code pager} to obtain the window of entities to return. * - * @param type type of data to return - * @param hql hql query to execute - * @param pager pager to obtan the correct window of data - * @param params params of the query - * @return entities of the paginated query result + * @param hql the HQL query + * @param pager pager to obtain the correct window of data + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entities E of the paginated query result * @throws TopiaException if any pb while getting datas * @see TopiaPagerBean * @since 2.6.12 */ - <R> List<R> findAllByQueryAndPager(Class<R> type, - String hql, - TopiaPagerBean pager, - Object... params) throws TopiaException; + List<E> findAllByQueryAndPager(String hql, + TopiaPagerBean pager, + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets a page of entities of the given select {@code hql} query using the + * Finds a page of entities R of the given select {@code hql} query using the * {@code pager} to obtain the window of entities to return. * - * @param hql hql query to execute - * @param pager pager to obtan the correct window of data - * @param params params of the query - * @return entities of the paginated query result + * @param type the expected result type + * @param hql the HQL query + * @param pager pager to obtain the correct window of data + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] + * @return entities R of the paginated query result * @throws TopiaException if any pb while getting datas * @see TopiaPagerBean * @since 2.6.12 */ - List<E> findAllByQueryAndPager(String hql, - TopiaPagerBean pager, - Object... params) throws TopiaException; + <R> List<R> findAllByQueryAndPager(Class<R> type, + String hql, + TopiaPagerBean pager, + Object... propertyNamesAndValues) throws TopiaException; /** - * Gets all entites for the dao entity type order by given {@code propertyNames}. - * <p/> - * You can add on each {@code property} {@code ASC} ou {@code DESC} to - * fix order way (by default is {@code ASC}). + * Find all the entities E which given collection (propertyName) contains the + * given value * - * @param propertyNames property names of order to apply - * @return all entities of the dao entity type with given order + * @param propertyName the name of the property (must be a collection) + * @param value the value to use for find + * @return all the entities E found * @throws TopiaException if any pb while getting datas - */ - List<E> findAllWithOrder(String... propertyNames) - throws TopiaException; - - /** - * Récupère toutes les entités (du type géré par ce dao) dont la - * collection nommée {@code propertyName} contient la {@code property} - * donnée. - * - * @param propertyName le nom de la propriété - * @param property la propriété recherchée - * @return toutes les entités recherchées - * @throws TopiaException pour tout erreur lors de la recherche * @since 2.5.4 */ List<E> findAllContains(String propertyName, - Object property) throws TopiaException; + Object value) throws TopiaException; //------------------------------------------------------------------------// //-- existsByXXX methods -------------------------------------------------// @@ -503,7 +527,7 @@ * * @param id unique id of the entity to test existence. * @return true if entity exists, false otherwise - * @throws TopiaException for Topia errors + * @throws TopiaException for any error * @since 2.3.4 */ boolean existByTopiaId(String id) throws TopiaException; @@ -513,26 +537,30 @@ * propertyValue}. {@code others} properties can be added to test * existence. * - * @param propertyName first property name to test existence - * @param propertyValue first property value to test existence - * @param others altern propertyName and propertyValue + * @param propertyName the first property name to test existence + * @param propertyValue the first property value to test existence + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] * @return true if entity exists, false otherwise * @throws TopiaException for Topia errors * @since 2.3.4 */ - boolean existByProperties(String propertyName, Object propertyValue, - Object... others) throws TopiaException; + boolean existByProperties(String propertyName, + Object propertyValue, + Object... propertyNamesAndValues) throws TopiaException; /** - * Check the existence of an entity using a {@code hql} query. + * Check the existence of an entity using the given HQL query. * - * @param hql query used to test existence - * @param params params used by the query + * @param hql the HQL query + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] * @return true if entity exists, false otherwise * @throws TopiaException * @since 2.6.12 */ - boolean existsByQuery(String hql, Object... params) throws TopiaException; + boolean existsByQuery(String hql, + Object... propertyNamesAndValues) throws TopiaException; //------------------------------------------------------------------------// //-- countXXX methods ----------------------------------------------------// @@ -548,14 +576,17 @@ long count() throws TopiaException; /** - * Count the number of entities based on a {@code hql}. + * Count the number of entities based on a the given HQL query. * - * @param hql hql query to use + * @param hql the HQL query to use + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] * @return number of entities filtered by the query * @throws TopiaException if any pb while getting datas * @since 2.6.12 */ - long countByQuery(String hql, Object... params) throws TopiaException; + long countByQuery(String hql, + Object... propertyNamesAndValues) throws TopiaException; //------------------------------------------------------------------------// //-- other request methods -----------------------------------------------// @@ -568,13 +599,12 @@ * @param type the type of entity to search * @param entity the entity on which search is done * @param <R> type of entity to search - * @return the list of entities of the given type which uses the given - * entity + * @return the list of entities R which uses the given entity * @throws TopiaException if any problem while getting data * @since 2.3.0 */ - <R extends TopiaEntity> List<R> findUsages(Class<R> type, E entity) - throws TopiaException; + <R extends TopiaEntity> List<R> findUsages(Class<R> type, + E entity) throws TopiaException; /** * Find all usages of the given {@code entity}. @@ -587,8 +617,7 @@ * @since 2.3.0 */ - Map<Class<? extends TopiaEntity>, List<? extends TopiaEntity>> findAllUsages(E entity) - throws TopiaException; + Map<Class<? extends TopiaEntity>, List<? extends TopiaEntity>> findAllUsages(E entity) throws TopiaException; /** * Execute the count {@code hql} query and then synch the pager to this @@ -596,36 +625,55 @@ * {@link TopiaPagerBean#records} field and then adapt * the number of pages available and the current number page). * - * @param hql the count hql to execute - * @param pager the page to synch - * @param params params of the count query + * @param hql the HQL query to use + * @param pager pager to obtain the correct window of data + * @param propertyNamesAndValues the query parameters. Arguments are key-value paired : + * [propertyName;value;propertyName;value;...] * @throws TopiaException if any pb while getting datas * @see TopiaPagerBean * @since 2.6.12 */ void computeAndAddRecordsToPager(String hql, TopiaPagerBean pager, - Object... params) throws TopiaException; + Object... propertyNamesAndValues) throws TopiaException; //------------------------------------------------------------------------// //-- Misc methods --------------------------------------------------------// //------------------------------------------------------------------------// /** - * Get the entityEnum of the type of entity managed by this DAO. + * Return the class of the entity managed by this DAO. * - * @return entity type enum managed by this DAO + * @return this DAO's managed entity's class */ - TopiaEntityEnum getTopiaEntityEnum(); + Class<E> getEntityClass(); /** - * Get the type of entity managed by this DAO. + * Returns the context used by this DAO. * - * @return entity type managed by this DAO + * @return Returns the context. */ - Class<E> getEntityClass(); + TopiaContextImplementor getContext(); /** + * Method to invoke right after instance creation. It is done by the + * TopiaContext. + * + * @param context context + * @param entityClass entity class + * @throws TopiaException if any pb while init + */ + void init(TopiaContextImplementor context, + Class<E> entityClass) throws TopiaException; + + /** + * Get the entityEnum of the type of entity managed by this DAO. + * + * @return entity type enum managed by this DAO + */ + TopiaEntityEnum getTopiaEntityEnum(); + + /** * Obtains the batch size used to load data. * <p/> * Default value if 1000. @@ -644,25 +692,7 @@ void setBatchSize(int batchSize); /** - * When TopiaContextImpl create the TopiaDAOHibernate, it must call this - * method just after. - * - * @param context context - * @param entityClass entity class - * @throws TopiaException if any pb while init - */ - void init(TopiaContextImplementor context, Class<E> entityClass) - throws TopiaException; - - /** - * Return context used by this DAO. - * - * @return the context. - */ - TopiaContextImplementor getContext(); - - /** - * Create the simple hql query for the entity managed by the dao. + * Create the simple HQL query for the entity managed by the dao. * <p/> * A optional alias can be passed: * <p/> @@ -678,12 +708,16 @@ //-- Listener methods ----------------------------------------------------// //------------------------------------------------------------------------// + // TODO AThimel 20/07/13 Javadoc void addTopiaEntityListener(TopiaEntityListener listener); + // TODO AThimel 20/07/13 Javadoc void addTopiaEntityVetoable(TopiaEntityVetoable vetoable); + // TODO AThimel 20/07/13 Javadoc void removeTopiaEntityListener(TopiaEntityListener listener); + // TODO AThimel 20/07/13 Javadoc void removeTopiaEntityVetoable(TopiaEntityVetoable vetoable); /** @@ -694,9 +728,13 @@ * @param actions encoded actions * @return la liste des permissions * @throws TopiaException if any pb while getting datas - * @deprecated since 2.6.14, {@code TopiaQuery} will be removed in version 3.0 + * @since 2.6.14 + * @deprecated {@code TopiaQuery} will be removed in version 3.0 + * @deprecated topia-service-security will be removed in 3.0 */ - List<Permission> getRequestPermission(String topiaId, int actions) - throws TopiaException; + @Deprecated + List<Permission> getRequestPermission(String topiaId, + int actions) throws TopiaException; + } //TopiaDAO 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 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaDAOImpl.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -341,9 +341,9 @@ } @Override - public E create(Object... properties) throws TopiaException { + public E create(Object... propertyNamesAndValues) throws TopiaException { - int propertiesLength = properties.length; + int propertiesLength = propertyNamesAndValues.length; Preconditions.checkArgument(propertiesLength % 2 == 0, "Wrong number of argument " + propertiesLength @@ -351,8 +351,8 @@ Map<String, Object> map = new HashMap<String, Object>(); for (int i = 0; i < propertiesLength; ) { - Object propertyName = properties[i++]; - Object value = properties[i++]; + Object propertyName = propertyNamesAndValues[i++]; + Object value = propertyNamesAndValues[i++]; Preconditions.checkArgument( propertyName instanceof String, "Argument at position [" + (i - 1) + "] " + @@ -443,9 +443,9 @@ @Override public E findByProperties(String propertyName, Object value, - Object... others) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Map<String, Object> properties = - convertPropertiesArrayToMap(propertyName, value, others); + convertPropertiesArrayToMap(propertyName, value, propertyNamesAndValues); E result = findByProperties(properties); return result; } @@ -487,9 +487,9 @@ @Override public List<E> findAllByProperties(String propertyName, Object value, - Object... others) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Map<String, Object> properties = - convertPropertiesArrayToMap(propertyName, value, others); + convertPropertiesArrayToMap(propertyName, value, propertyNamesAndValues); List<E> result = findAllByProperties(properties); return result; } @@ -533,17 +533,17 @@ @Override public E findContains(String propertyName, - Object property) throws TopiaException { + Object value) throws TopiaException { E find = context.findUnique("from " + getEntityClass().getName() + - " WHERE :property in elements(" + propertyName + ")", "property", property); + " WHERE :property in elements(" + propertyName + ")", "property", value); return find; } @Override public List<E> findAllContains(String propertyName, - Object property) throws TopiaException { + Object value) throws TopiaException { List<E> find = context.findAll("from " + getEntityClass().getName() + - " WHERE :property in elements(" + propertyName + ")", "property", property); + " WHERE :property in elements(" + propertyName + ")", "property", value); return find; } @@ -555,9 +555,9 @@ @Override public boolean existByProperties(String propertyName, Object propertyValue, - Object... others) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Map<String, Object> properties = - convertPropertiesArrayToMap(propertyName, propertyValue, others); + convertPropertiesArrayToMap(propertyName, propertyValue, propertyNamesAndValues); try { Criteria criteria = createCriteria(FlushMode.AUTO); criteria.add(Restrictions.allEq(properties)); @@ -668,26 +668,26 @@ @Override public boolean existsByQuery(String hql, - Object... params) throws TopiaException { - long count = countByQuery(hql, params); + Object... propertyNamesAndValues) throws TopiaException { + long count = countByQuery(hql, propertyNamesAndValues); return count > 0; } @Override public long countByQuery(String hql, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Preconditions.checkNotNull(StringUtils.isNotBlank(hql)); Preconditions.checkArgument(hql.toUpperCase().trim().startsWith("SELECT COUNT(")); - Long result = findByQuery(Long.class, hql, params); + Long result = findByQuery(Long.class, hql, propertyNamesAndValues); return result; } @Override public E findByQuery(String hql, - Object... params) throws TopiaException { - E result = findByQuery(getEntityClass(), hql, params); + Object... propertyNamesAndValues) throws TopiaException { + E result = findByQuery(getEntityClass(), hql, propertyNamesAndValues); return result; } @@ -707,57 +707,57 @@ @Override public List<E> findAllByQuery(String hql, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { - List<E> result = findAllByQuery(getEntityClass(), hql, params); + List<E> result = findAllByQuery(getEntityClass(), hql, propertyNamesAndValues); return result; } @Override public <R> List<R> findAllByQuery(Class<R> type, String hql, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Preconditions.checkNotNull(type); Preconditions.checkNotNull(hql); - List<R> result = getContext().findAll(hql, params); + List<R> result = getContext().findAll(hql, propertyNamesAndValues); return result; } @Override public Iterable<E> findAllLazyByQuery(String hql, - Object... params) throws TopiaException { - Iterable<E> result = findAllLazyByQuery(batchSize, hql, params); + Object... propertyNamesAndValues) throws TopiaException { + Iterable<E> result = findAllLazyByQuery(batchSize, hql, propertyNamesAndValues); return result; } @Override public <R> Iterable<R> findAllLazyByQuery(Class<R> type, String hql, - Object... params) throws TopiaException { - Iterable<R> result = findAllLazyByQuery(type, batchSize, hql, params); + Object... propertyNamesAndValues) throws TopiaException { + Iterable<R> result = findAllLazyByQuery(type, batchSize, hql, propertyNamesAndValues); return result; } @Override public Iterable<E> findAllLazyByQuery(int batchSize, String hql, - Object... params) throws TopiaException { - return findAllLazyByQuery(getEntityClass(), batchSize, hql, params); + Object... propertyNamesAndValues) throws TopiaException { + return findAllLazyByQuery(getEntityClass(), batchSize, hql, propertyNamesAndValues); } @Override public <R> Iterable<R> findAllLazyByQuery(Class<R> type, int batchSize, String hql, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { final Iterator<R> iterator = new FindAllIterator<E, R>(this, type, batchSize, hql, - params); + propertyNamesAndValues); Iterable<R> result = new Iterable<R>() { @Override public Iterator<R> iterator() { @@ -772,11 +772,11 @@ String hql, int startIndex, int endIndex, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Preconditions.checkNotNull(type); Preconditions.checkNotNull(hql); - List<R> result = getContext().find(hql, startIndex, endIndex, params); + List<R> result = getContext().find(hql, startIndex, endIndex, propertyNamesAndValues); return result; } @@ -784,12 +784,12 @@ public List<E> findAllByQueryWithBound(String hql, int startIndex, int endIndex, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { List<E> result = findAllByQueryWithBound(getEntityClass(), hql, startIndex, endIndex, - params); + propertyNamesAndValues); return result; } @@ -797,7 +797,7 @@ public <R> List<R> findAllByQueryAndPager(Class<R> type, String hql, TopiaPagerBean pager, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { Preconditions.checkNotNull(pager); Preconditions.checkNotNull(hql); @@ -810,28 +810,28 @@ List<R> result = findAllByQueryWithBound(type, hql, (int) pager.getRecordStartIndex(), (int) pager.getRecordEndIndex() - 1, - params); + propertyNamesAndValues); return result; } @Override public List<E> findAllByQueryAndPager(String hql, TopiaPagerBean pager, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { List<E> result = findAllByQueryAndPager(getEntityClass(), hql, pager, - params); + propertyNamesAndValues); return result; } @Override public void computeAndAddRecordsToPager(String hql, TopiaPagerBean pager, - Object... params) throws TopiaException { + Object... propertyNamesAndValues) throws TopiaException { - long records = countByQuery(hql, params); + long records = countByQuery(hql, propertyNamesAndValues); pager.setRecords(records); PagerBeanUtil.computeRecordIndexesAndPagesNumber(pager); Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntity.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntity.java 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntity.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -49,10 +49,10 @@ import java.util.List; /** - * The TopiaEntity is the main interface for each entities generated with {@link + * The TopiaEntity is the main interface for each entity generated with {@link * TopiaMetaTransformer}. An entity is simply a persistent bean mapped with - * hibernate. The manipulation on entities (create, update, delete, find) is - * made by the dao associated. The corresponding dao interface is {@link + * Hibernate. The manipulation on entities (create, update, delete, find) is + * made by the DAO associated. The corresponding DAO interface is {@link * TopiaDAO}. * <p/> * Setter methods have to be used only in internal. They are in the interface to @@ -95,7 +95,7 @@ /** * Unique technical Id of the entity. This id contains the full qualified - * name of the entity interface. This id has also an index and his used to + * name of the entity interface. This id has also an index and is used to * identify uniquely the entity in the database. * * @return the technical Id of the entity @@ -167,84 +167,120 @@ /** * @return all object that must be deleted if this object is deleted * @throws TopiaException if any pb + * @deprecated from 3.0, method will be moved to entity's generated DAO (cf http://nuiton.org/issues/2776) */ + @Deprecated List<TopiaEntity> getComposite() throws TopiaException; /** * @return all object that are aggregate with this instance, aggreate object * are not removed automaticaly * @throws TopiaException if any pb + * @deprecated from 3.0, method will be moved to entity's generated DAO (cf http://nuiton.org/issues/2776) */ + @Deprecated List<TopiaEntity> getAggregate() throws TopiaException; /** - * Add listener for property writing. + * Route the entity using a {@code visitor}. * - * @param propertyName name of property to listen - * @param listener the listener to register + * @param visitor to used + * @throws TopiaException for all type of error */ - void addPropertyChangeListener(String propertyName, - PropertyChangeListener listener); + void accept(EntityVisitor visitor) throws TopiaException; + //------------------------------------------------------------------------// + //-- PropertyListener (read) methods -------------------------------------// + //------------------------------------------------------------------------// + /** - * Add listener for property writing. + * Add listener for property reading. * * @param listener the listener to register */ - void addPropertyChangeListener(PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void addPropertyListener(PropertyChangeListener listener); - void addVetoableChangeListener(String propertyName, - VetoableChangeListener vetoable); - - void addVetoableChangeListener(VetoableChangeListener vetoable); - - void removePropertyChangeListener(String propertyName, - PropertyChangeListener listener); - - void removePropertyChangeListener(PropertyChangeListener listener); - - void removeVetoableChangeListener(String propertyName, - VetoableChangeListener vetoable); - - void removeVetoableChangeListener(VetoableChangeListener vetoable); - /** * Add listener for property reading. * * @param propertyName the property name to listen * @param listener the listener to register */ + // TODO AThimel 20/07/13 Javadoc void addPropertyListener(String propertyName, PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void removePropertyListener(PropertyChangeListener listener); + + // TODO AThimel 20/07/13 Javadoc + void removePropertyListener(String propertyName, + PropertyChangeListener listener); + + //------------------------------------------------------------------------// + //-- PropertyChangeListener (write) methods ------------------------------// + //------------------------------------------------------------------------// + /** - * Add listener for property reading. + * Add listener for property writing. * * @param listener the listener to register */ - void addPropertyListener(PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void addPropertyChangeListener(PropertyChangeListener listener); - void addVetoableListener(String propertyName, - VetoableChangeListener vetoable); + /** + * Add listener for property writing. + * + * @param propertyName name of property to listen + * @param listener the listener to register + */ + // TODO AThimel 20/07/13 Javadoc + void addPropertyChangeListener(String propertyName, + PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void removePropertyChangeListener(PropertyChangeListener listener); + + // TODO AThimel 20/07/13 Javadoc + void removePropertyChangeListener(String propertyName, + PropertyChangeListener listener); + + //------------------------------------------------------------------------// + //-- VetoableListener (read) methods -------------------------------------// + //------------------------------------------------------------------------// + + // TODO AThimel 20/07/13 Javadoc void addVetoableListener(VetoableChangeListener vetoable); - void removePropertyListener(String propertyName, - PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void addVetoableListener(String propertyName, + VetoableChangeListener vetoable); - void removePropertyListener(PropertyChangeListener listener); + // TODO AThimel 20/07/13 Javadoc + void removeVetoableListener(VetoableChangeListener vetoable); + // TODO AThimel 20/07/13 Javadoc void removeVetoableListener(String propertyName, VetoableChangeListener vetoable); - void removeVetoableListener(VetoableChangeListener vetoable); + //------------------------------------------------------------------------// + //-- VetoableChangeListener (write) methods ------------------------------// + //------------------------------------------------------------------------// - /** - * Route the entity using a {@code visitor}. - * - * @param visitor to used - * @throws TopiaException for all type of error - */ - void accept(EntityVisitor visitor) throws TopiaException; + // TODO AThimel 20/07/13 Javadoc + void addVetoableChangeListener(VetoableChangeListener vetoable); + // TODO AThimel 20/07/13 Javadoc + void addVetoableChangeListener(String propertyName, + VetoableChangeListener vetoable); + + // TODO AThimel 20/07/13 Javadoc + void removeVetoableChangeListener(VetoableChangeListener vetoable); + + // TODO AThimel 20/07/13 Javadoc + void removeVetoableChangeListener(String propertyName, + VetoableChangeListener vetoable); + } //TopiaEntity Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntityEnum.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntityEnum.java 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaEntityEnum.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -128,4 +128,5 @@ * {@code false} otherwise. */ boolean accept(Class<? extends TopiaEntity> klass); + } Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaIdFactory.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaIdFactory.java 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaIdFactory.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -8,11 +8,10 @@ */ public interface TopiaIdFactory { + // TODO AThimel 20/07/13 Javadoc <E extends TopiaEntity> String newTopiaId(Class<E> entityClass, TopiaEntity topiaEntity); - // TODO brendan 10/07/13 deprecated ? - // TODO tchemit 11/07/13, We still use this paradigm in Topia, prefer not to remove this contract ? - @Deprecated + // TODO AThimel 20/07/13 Javadoc <E extends TopiaEntity> Class<E> getClassName(String topiaId); } Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaPersistenceHelper.java =================================================================== --- trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaPersistenceHelper.java 2013-07-19 15:21:11 UTC (rev 2774) +++ trunk/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaPersistenceHelper.java 2013-07-19 23:32:02 UTC (rev 2775) @@ -34,10 +34,15 @@ */ public interface TopiaPersistenceHelper<T extends TopiaEntityEnum> { + // TODO AThimel 20/07/13 Javadoc <E extends TopiaEntity> T getEntityEnum(Class<E> type); - <E extends TopiaEntity> TopiaDAO<E> getDAO(TopiaContext tx, Class<E> type); + // TODO AThimel 20/07/13 Javadoc + <E extends TopiaEntity> TopiaDAO<E> getDAO(TopiaContext tx, + Class<E> type); - <E extends TopiaEntity> TopiaDAO<E> getDAO(TopiaContext tx, T type); + // TODO AThimel 20/07/13 Javadoc + <E extends TopiaEntity> TopiaDAO<E> getDAO(TopiaContext tx, + T type); }