[Wikitty-commits] r1276 - in trunk: src/site/rst/user wikitty-api/src/main/java/org/nuiton/wikitty/query wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions

2 Jan 2012

Author: bpoussin
Date: 2012-01-02 19:45:36 +0100 (Mon, 02 Jan 2012)
New Revision: 1276

Url: http://nuiton.org/repositories/revision/wikitty/1276

Log:
debut de documentation de l'API Query

Added:
   trunk/src/site/rst/user/query.rst
Modified:
   trunk/src/site/rst/user/search.rst
   trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/WikittyQueryMaker.java
   trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions/ElementField.java

Added: trunk/src/site/rst/user/query.rst
===================================================================

--- trunk/src/site/rst/user/query.rst	                        (rev 0)
+++ trunk/src/site/rst/user/query.rst	2012-01-02 18:45:36 UTC (rev 1276)
@@ -0,0 +1,364 @@
+======================
+Recherche avec Wikitty
+======================
+
+Wikitty permet de rechercher parmis les entités enregistrées tout en fournissant
+les fonctionalités de pagination. Pour cela vous pouvez construire
+programmatiquement vos recherches en utilisant WikittyQueryMaker ou de façon
+textuel en utilisant WikittyQueryParser.
+
+Au final vous obtenez dans les deux cas un WikittyQuery utilisable pour vos
+recherche pour les méthodes WikittyClient.findXXXX.
+
+Utilisation via WikittyClient
+-----------------------------
+
+Les requêtes peuvent être utilisée dans les méthodes:
+
+- findAllByQuery(Query): WikittyQueryResult<String>
+- findByQuery(Query): String
+- findAllByQuery(Class<E>, Query): WikittyQueryResult<E>
+- findByQuery(Class<E>, Query): E
+
+Dans les deux premières méthodes les résultats seront retournés de façon brut
+sous forme de String. Si le résultat représente une entité, le String sera son
+id. Si le résultat représente une Date, la date sera la valeur tel que retournée
+par la la méthode WikittyUtil.toString(Date)
+
+Les deux dernières méthodes essaient de convertir le résultat en objet de la
+classe passée en paramètre. Par exemple si vous savez que le résultat sont des
+valeurs numeriques vous pouvez passer Number.class en argument.
+
+
+Vous pouvez aussi utiliser les méthodes suivantes qui construiront les requêtes
+pour vous:
+
+- findAllByExample(E): List<E>
+- findByExample(E): E
+
+Structure d'une requête
+-----------------------
+
+Par exemple si vous souhaitez faire la recherche sur::
+
+  User.lastname=poussin AND User.firstname=benjamin
+
+Vous pouvez soit utiliser le WikittyQueryMaker::
+
+  WikittyQuery query = new WikittyQueryMaker()
+     .and()
+         .eq(User.ELEMENT_FIELD_USER_LASTNAME, "poussin")
+         .eq(User.ELEMENT_FIELD_USER_FIRSTNAME, "benjamin")
+     .end();
+
+Le end() indique que la condition est fini et que l'on souhaite la query
+
+Vous pouvez aussi utiliser WikittyQueryParser pour faire le même travail, mais
+il est plus sûr d'utiliser le WikittyQueryMaker tant que vous le pouvez::
+
+  WikittyQueryParser parser = WikittyQueryParser.parse(
+      "User.lastname=poussin User.firstname=benjamin");
+
+S'il n'y a pas d'opérateur entre deux contrainte un AND est automatiquement 
+ajouté.
+
+Les contraintes disponibles
+---------------------------
+
+De nombreuses contraintes sont disponibles pour créer vos recherches :
+
+* Egalité : eq - Vérifie si un champ est égal a une valeur, si le champs est un
+  champs texte, il est possible d'ajouter des "*" en début et en fin de la
+  chaîne de recherche pour faire l'équivalent d'un startsWith ou endsWith. Si
+  vous utilisez WikittyQueryMaker les méthodes sw (startsWith) et ew (endsWith)
+  font se travail pour vous.::
+
+    WikittyQuery q = new WikittyQueryMaker().eq(User.ELEMENT_FIELD_USER_LASTNAME, "poussin").end();
+    WikittyQuery q = new WikittyQueryMaker().eq(User.ELEMENT_FIELD_USER_LASTNAME, "*ssin").end();
+    WikittyQuery q = new WikittyQueryMaker().ew(User.ELEMENT_FIELD_USER_LASTNAME, "ssin").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=poussin");
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=*ssin");
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=*ssin");
+
+* Non égalité : neq - Vérifie si un champ n'est pas égal a une valeur. De la
+  même façon que le eq, il est possible d'ajouter des '*'. Ou d'utiliser les
+  méthode notsw et notew.::
+
+    WikittyQuery q = new WikittyQueryMaker().ne(User.ELEMENT_FIELD_USER_LASTNAME, "poussin").end();
+    WikittyQuery q = new WikittyQueryMaker().ne(User.ELEMENT_FIELD_USER_LASTNAME, "*ssin").end();
+    WikittyQuery q = new WikittyQueryMaker().notew(User.ELEMENT_FIELD_USER_LASTNAME, "ssin").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=poussin");
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=*ssin");
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=*ssin");
+
+* Contient tous : containsAll - Vérifie si un champ multivalué contient au moins
+  une valeur de la liste des valeurs passées en argument::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .containsOne(User.ELEMENT_FIELD_USER_LASTNAME, "poussin", "couteau").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname={poussin, couteau}");
+
+* Egalité d'extension : exteq - Vérifie si un Wikitty possède une extension::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .exteq(User.EXT_USER).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("extension=User");
+
+* Non égalité d'extension : extne - Vérifie qu'un Wikitty ne porte pas une
+extension.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .extne(User.EXT_USER).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("extension!=User");
+
+* ContainsAll d'extension : extContainsAll - Vérifie si un Wikitty possède tous
+  les extensions::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .extContainsAll(User.EXT_USER, Employee.EXT_EMPLOYEE).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("extension=[User, Employee]");
+
+* Égalité d'extension : ideq - Vérifie qu'un Wikitty porte l'identifiant::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .ideq(User.EXT_USER).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("id=1234567-1234-1234567");
+
+* Non égalité d'identifiant : idneq - Vérifie qu'un Wikitty ne porte pas
+l'identifiant.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .idne(User.EXT_USER).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("id!=1234567-1234-1234567");
+
+* Similitude : like - Vérifie qu'une chaîne de caractère est égale à une autre
+  sans tenir compte de la case ni des accents. Cette opérateur ne recherche que
+  de façon textuelle, vous pouvez ajouter des '*' en début et fin de d'expression::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .like(User.ELEMENT_FIELD_USER_FIRSTNAME, "helene").end();
+    WikittyQuery q = new WikittyQueryMaker()
+        .like(User.ELEMENT_FIELD_USER_FIRSTNAME, "*lene").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.fistname LIKE helene");
+    WikittyQuery q = WikittyQueryParser.parse("User.fistname LIKE *lene");
+
+* Non similitude : unlike - Vérifie qu'une chaîne de caractère n'est pas égale à une autre
+  sans tenir compte de la case ni des accents. Cette opérateur ne recherche que
+  de façon textuelle, vous pouvez ajouter des '*' en début et fin de d'expression::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .unlike(User.ELEMENT_FIELD_USER_FIRSTNAME, "helene").end();
+    WikittyQuery q = new WikittyQueryMaker()
+        .unlike(User.ELEMENT_FIELD_USER_FIRSTNAME, "*lene").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.fistname UNLIKE helene");
+    WikittyQuery q = WikittyQueryParser.parse("User.fistname UNLIKE *lene");
+
+* Supérieur strictement : gt - Vérifie qu'un champ est strictement supérieur à
+  une valeur. Cette condition s'applique surtout sur les champs de type Date et
+  Number::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .gt(User.ELEMENT_FIELD_USER_AGE, 18).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.age > 18");
+
+* Supérieur ou égal : ge - Vérifie si un champ est supérieur ou égal à une
+valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .ge(User.ELEMENT_FIELD_USER_AGE, 18).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.age >= 18");
+
+* Inférieur strictement : lt - Vérifie si un champ est strictement inférieur à
+une valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .lt(User.ELEMENT_FIELD_USER_AGE, 18).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.age < 18");
+
+* Inférieur ou égal : le - Vérifie si un champ est inférieur ou égal à une
+valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .le(User.ELEMENT_FIELD_USER_AGE, 18).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.age <= 18");
+
+* Entre : bw - Vérifie si un champ est compris entre deux valeurs.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .bw(Product.ELEMENT_FIELD_PRODUCT_PRICE, 2, 2.50).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("Product.price=[2 TO 2.5]");
+
+* Commence par : sw - Vérifie si un champ de type chaîne commence par une valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .sw(User.ELEMENT_FIELD_USER_LASTNAME, "pous").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=pous*");
+
+* Ne commence pas par : notsw - Vérifie si un champ de type chaîne ne commence pas
+par une valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .notsw(User.ELEMENT_FIELD_USER_LASTNAME, "pous").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=pous*");
+
+* Termine par : ew - Vérifie si un champ de type chaîne termine par une valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .ew(User.ELEMENT_FIELD_USER_LASTNAME, "sin").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=sin*");
+
+* Ne termine pas par : notew - Vérifie si un champs de type chaîne ne termine
+pas par une valeur.::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .notew(User.ELEMENT_FIELD_USER_LASTNAME, "pous").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=pous*");
+
+* Mot-clé : keyword - Vérifie si la valeur est présente dans n'importe quel
+  champ de n'importe quelle extension en fulltext (pas de prise en compte de la
+  case out des accents).::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .keyword("partout").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("partout");
+
+* Nul : isNull - Vérifie si la valeur d'un champ est nulle::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .isNull(User.ELEMENT_FIELD_USER_LASTNAME).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname=NULL");
+
+* Non nul : isNotNull - Vérifie si la valeur d'un champ n'est pas nulle.
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .isNotNull(User.ELEMENT_FIELD_USER_LASTNAME).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("User.lastname!=NULL");
+
+* False : rFalse - retourne toujours faux::
+
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .rFalse().end();
+
+    WikittyQuery q = WikittyQueryParser.parse("FALSE");
+
+* True : rTrue - retourne toujours vrai::
+
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .rTrue().end();
+
+    WikittyQuery q = WikittyQueryParser.parse("TRUE");
+
+Les noeuds à sous-requête
+-------------------------
+
+* Les noeuds à sous requêtes permettent de faire des requêtes complexes.
+
+* Non : not - Résultat inverse de la sous-requête.
+
+* Ou : or - Ou entre les différentes sous-requêtes.
+
+* Et : and - Et entre les différentes sous-requêtes.
+
+* Requête associée : in - Permet d'effectuer des jointures.
+
+* Selection : select - Ajout d'un select pour définir le champs à retourner au
+  lieu de l'id
+
+
+Recherche avancée
+-----------------
+
+Si vous souhaitez mettre des espaces dans une expression texte avec le parser
+il faut utiliser les guillemets pour encadrer la chaine.::
+
+    WikittyQuery q = WikittyQueryParser.parse("simple OR \"la jolie chaine que je recherche\"");
+
+Il est possible de faire une recherche sur un nom de champs qui peut⁻être utilisé
+par différente extension. Pour cela on remplace le nom d'extension par '*'::
+
+    WikittyQuery q = new WikittyQueryMaker()
+        .eq(new ElementField(ElementField.ALL_EXTENSION, "name"), "poussin").end();
+
+    WikittyQuery q = WikittyQueryParser.parse("*.name==poussin");
+
+Dans ce cas la recherche est une recherche fulltext qui peut-être utilisé
+quelque soit le type du champs. Mais si vous souhaitez restrainte la recherche
+au champs d'un certain type vous pouvez ajouter le type à la fin.::
+
+    Date _1950 = new Date(...);
+    Date _1960 = new Date(...);
+    WikittyQuery q = new WikittyQueryMaker()
+        bw.(new ElementField("birthday", FieldType.TYPE.DATE), _1950, _1960).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("*.birthday.DATE=[\"01/01/1950\" TO \"01/01/1961\"]");
+
+Il est aussi possible de faire une recherche fulltext, c'est à dire sur tous les
+champs de toutes les extentions::
+
+    Date _1950 = new Date(...);
+    Date _1960 = new Date(...);
+    WikittyQuery q = new WikittyQueryMaker()
+        eq.(Element.ALL_FIELD, "poussin).end();
+
+    WikittyQuery q = WikittyQueryParser.parse("*=poussin");
+
+
+Les autres valeurs d'une requête
+--------------------------------
+
+* Nom : name - Nommage de la requêtes.
+
+* Les requêtes permettent d'ajouter un ordre ou des facettes :
+
+* Premier index : first - Permet de définir le premier index à retourner. Principalement utilisé pour la pagination.
+
+* Nombre : limit - Permet de définir le dernier index à retourner. Principalement utilisé pour la pagination.
+
+* [TODO] facetMinCount
+
+* [TODO] facetLimit
+
+* [TODO] facetSort
+
+* [TODO] facetExtension
+
+* [TODO] facetField
+
+* [TODO] facetQuery
+
+* Tri : sortAscending - Ajout d'un ou plusieurs champs pour le tri ascendant du résultat.
+
+* Tri : sortDescending - Ajout d'un ou plusieurs champs pour le tri descendant du résultat.
+
+Les résultats
+-------------
+
+Lorsqu'on effectue une recherche, on obtient un WikittyQueryResult. En effet, les
+résultats étant paginés, on obtient tout ou partie des résultats.
+Un WikittyQueryResult contient le nombre total de résultats, les résultats de la page
+ainsi que le premier index, le nombre de résultats et les facettes si elles ont
+été utilisées pour la recherche.

Modified: trunk/src/site/rst/user/search.rst
===================================================================
--- trunk/src/site/rst/user/search.rst	2012-01-02 17:58:20 UTC (rev 1275)
+++ trunk/src/site/rst/user/search.rst	2012-01-02 18:45:36 UTC (rev 1276)
@@ -26,6 +26,8 @@
 Recherche avec Wikitty
 ======================
 
+Cette API est complètement dépréciée, il faut maintenant utiliser l'API QUERY
+
 Wikitty permet de rechercher parmis les entités enregistrées tout en fournissant
 les fonctionalités de pagination. Pour cela vous pouvez construire
 programmatiquement vos recherches en utilisant un système de Criteria.

Modified: trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/WikittyQueryMaker.java
===================================================================
--- trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/WikittyQueryMaker.java	2012-01-02 17:58:20 UTC (rev 1275)
+++ trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/WikittyQueryMaker.java	2012-01-02 18:45:36 UTC (rev 1276)
@@ -453,7 +453,7 @@
      * @return {@code this} with the {@code extneq} restriction added.
      * @see {@link NotEquals}
      */
-    public WikittyQueryMaker extneq(String extensionName) {
+    public WikittyQueryMaker extne(String extensionName) {
         return ne(Element.EXTENSION, extensionName);
     }
 
@@ -463,10 +463,10 @@
      * Restrict search to wikitties that do not have the id given in parameter.
      *
      * @param idOrWikitty the id the wikitties must not have.
-     * @return {@code this} with the {@code idneq} restriction added.
+     * @return {@code this} with the {@code idne} restriction added.
      * @see {@link NotEquals}
      */
-    public WikittyQueryMaker idneq(Object idOrWikitty) {
+    public WikittyQueryMaker idne(Object idOrWikitty) {
         return ne(Element.ID, idOrWikitty);
     }
 

Modified: trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions/ElementField.java
===================================================================
--- trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions/ElementField.java	2012-01-02 17:58:20 UTC (rev 1275)
+++ trunk/wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions/ElementField.java	2012-01-02 18:45:36 UTC (rev 1276)
@@ -4,8 +4,6 @@
 import org.apache.commons.logging.LogFactory;
 import org.nuiton.wikitty.WikittyUtil;
 import org.nuiton.wikitty.entities.FieldType;
-import org.nuiton.wikitty.entities.WikittyExtension;
-import org.nuiton.wikitty.entities.WikittyField;
 
 /**
  * Element qui porte sur un champs. Le champs doit-ete de la forme

    

[Wikitty-commits] r1276 - in trunk: src/site/rst/user wikitty-api/src/main/java/org/nuiton/wikitty/query wikitty-api/src/main/java/org/nuiton/wikitty/query/conditions

bpoussin＠users.nuiton.org