Author: jcouteau Date: 2011-08-16 11:21:41 +0200 (Tue, 16 Aug 2011) New Revision: 1154 Url: http://nuiton.org/repositories/revision/wikitty/1154 Log: Improve javadoc Modified: trunk/wikitty-api/src/main/java/org/nuiton/wikitty/search/Search.java Modified: trunk/wikitty-api/src/main/java/org/nuiton/wikitty/search/Search.java =================================================================== --- trunk/wikitty-api/src/main/java/org/nuiton/wikitty/search/Search.java 2011-08-16 09:21:25 UTC (rev 1153) +++ trunk/wikitty-api/src/main/java/org/nuiton/wikitty/search/Search.java 2011-08-16 09:21:41 UTC (rev 1154) @@ -37,13 +37,21 @@ import org.nuiton.wikitty.WikittyUtil; /** - * Helper to create a criteria with a restriction - * <p/> + * Helper to create a criteria with restrictions. + * + * To create a search, use Search.query() and add restrictions to that + * query. In the end, create the criteria from the query and use it on find + * methods. + * * Element : - * <extensionName>.<fieldName>[.<fieldType>] : search on an extension and field with specific type (optional) - * Criteria.ALL_EXTENSIONS.<fieldName>.<fieldType> : search on all extension and field name with specific type - * <p/> + * * <extensionName>.<fieldName>[.<fieldType>] : search on an extension and field with specific type (optional) + * * Criteria.ALL_EXTENSIONS.<fieldName>.<fieldType> : search on all extension and field name with specific type + * * <fieldType> specify search on field as NUMERIC, STRING, WIKITTY, BOOLEAN, DATE. Use Element.ElementType to specify type. + * + * Some patterns might be available depending on the restriction used. They are : + * * '*' replace any number of characters + * * '?' replace one character */ public class Search { @@ -122,11 +130,11 @@ } /** - * Create new query on existent criteria to add new constraint to existent - * criteria. + * Create a new query on an existing criteria to add new constraints to + * the existing criteria. * - * @param criteria - * @return + * @param criteria the existing criteria + * @return a new query to add constraints to the criteria. */ public static Search query(Criteria criteria) { Search search = query(); @@ -145,9 +153,17 @@ /** * Contains. * - * @param element - * @param values - * @return + * Search on lists (multivalued fields) that a field contains all the values + * of the list given in parameter. + * + * Ex : The field with value [toto,titi,tutu] contains [titi,tutu] but not + * [titi,tutu,tata] + * + * Ps : Use wildcards if you search for substrings. + * + * @param element the element on which the restriction is put + * @param values the values to search in the element + * @return {@code this} with the {@code contains} restriction added. */ public Search contains(String element, Collection<String> values) { restrictions.add(RestrictionHelper.contains(elt(element), @@ -158,10 +174,18 @@ /** * Contains. * - * @param element - * @param value1 - * @param values - * @return + * Search on lists (multivalued fields) that a field contains all the values + * given in parameter. + * + * Ex : The field with value [toto,titi,tutu] contains [titi,tutu] but not + * [titi,tutu,tata] + * + * Ps : Use wildcards if you search for substrings. + * + * @param element the element on which the restriction is put + * @param value1 first value to search in the field + * @param values list of values to search in the field + * @return {@code this} with the {@code contains} restriction added. */ public Search contains(String element, String value1, String ... values) { restrictions.add(RestrictionHelper.contains(elt(element), @@ -170,11 +194,18 @@ } /** - * Contains. + * In. * - * @param element - * @param values - * @return + * Search if a field is contained in the list of values in parameter + * + * Ex : The field with value titi is in [titi,tutu] but not in + * [tutu,tata] + * + * Ps : Use wildcards in the values if you search for substrings. + * + * @param element the element on which the restriction is put + * @param values list of values the field must be in + * @return {@code this} with the {@code in} restriction added. */ public Search in(String element, Collection<String> values) { restrictions.add(RestrictionHelper.in(elt(element), @@ -183,12 +214,19 @@ } /** - * Contains. + * In. * - * @param element - * @param value1 - * @param values - * @return + * Search if a field is contained in the list of values in parameter + * + * Ex : The field with value titi is in [titi,tutu] but not in + * [tutu,tata] + * + * Ps : Use wildcards in the values if you search for substrings. + * + * @param element the element on which the restriction is put + * @param value1 first value the field must be in + * @param values list of values the field must be in + * @return {@code this} with the {@code in} restriction added. */ public Search in(String element, String value1, String ... values) { restrictions.add(RestrictionHelper.in(elt(element), @@ -199,8 +237,12 @@ /** * Equals. * - * @param element - * @param value + * Restrict search so that the field value equals the parameter. + * + * You might use patterns in your equality. + * + * @param element the field on which the search is made + * @param value the value the element must be equals to * @return {@code this} */ public Search eq(String element, String value) { @@ -209,10 +251,12 @@ } /** - * Looking find specific extension + * Extension equals. * - * @param value - * @return {@code this} + * Restrict search to wikitties that got the extension in parameter. + * + * @param value the extension to restrict the results to + * @return {@code this} with the {@code exteq} restriction added. */ public Search exteq(String value) { restrictions.add(RestrictionHelper.eq(elt(Element.ELT_EXTENSION), value)); @@ -220,10 +264,12 @@ } /** - * Looking find specific id + * Id equals. * - * @param value - * @return {@code this} + * Restrict search to wikitties that got the id in parameter. + * + * @param value the id to restrict the results to + * @return {@code this} with the {@code ideq} restriction added. */ public Search ideq(String value) { restrictions.add(RestrictionHelper.eq(elt(Element.ELT_ID), value)); @@ -231,11 +277,14 @@ } /** - * Equals each collection elements. + * Equals. * - * @param element - * @param values - * @return {@code this} + * Restrict search so that the field value equals all the members of the + * list in parameters. + * + * @param element the element on which the restriction is put + * @param values list of values that the element must be equals to + * @return {@code this} with the {@code ideq} restriction added. */ public Search eq(String element, Collection<String> values) { for (String value : values) { @@ -245,10 +294,12 @@ } /** - * Equals each collection elements. + * Extension equals. * - * @param values - * @return {@code this} + * Restrict search to wikitties that got all the extensions in parameter. + * + * @param values list of the extension to restrict the results to + * @return {@code this} with the {@code exteq} restriction added. */ public Search exteq(Collection<String> values) { for (String value : values) { @@ -259,10 +310,13 @@ /** * Not equals. + * + * Restrict search to elements that are not equals to the value given in + * parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put + * @param value the value the element must not be equals to. + * @return {@code this} with the {@code neq} restriction added. */ public Search neq(String element, String value) { restrictions.add(RestrictionHelper.neq(elt(element), value)); @@ -270,10 +324,13 @@ } /** - * Not equals. + * Extension not equals. * - * @param value - * @return {@code this} + * Restrict search to wikitties that do not get the extension given in + * parameter. + * + * @param value the extension that the wikitties must not have. + * @return {@code this} with the {@code extneq} restriction added. */ public Search extneq(String value) { restrictions.add(RestrictionHelper.neq(elt(Element.ELT_EXTENSION), value)); @@ -281,10 +338,12 @@ } /** - * Not equals. + * Id not equals. * - * @param value - * @return {@code this} + * Restrict search to wikitties that do not have the id given in parameter. + * + * @param value the id the wikitties must not have. + * @return {@code this} with the {@code idneq} restriction added. */ public Search idneq(String value) { restrictions.add(RestrictionHelper.neq(elt(Element.ELT_ID), value)); @@ -293,10 +352,12 @@ /** * Greater than. + * + * Search if an element value is greater than the parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put + * @param value the value to be compared to + * @return {@code this} with the {@code gt} restriction added. */ public Search gt(String element, String value) { restrictions.add(RestrictionHelper.great(elt(element), value)); @@ -304,11 +365,13 @@ } /** - * Greater or equals. + * Greater than or equals. + * + * Search if an element value is greater than or equals to the parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the field on which the search is made + * @param value the value to be compared to + * @return {@code this} with the {@code ge} restriction added. */ public Search ge(String element, String value) { restrictions.add(RestrictionHelper.greatEq(elt(element), value)); @@ -317,10 +380,12 @@ /** * Less than. + * + * Search if an element value is less than the parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put + * @param value the value to be compared to + * @return {@code this} with the {@code lt} restriction added. */ public Search lt(String element, String value) { restrictions.add(RestrictionHelper.less(elt(element), value)); @@ -328,11 +393,13 @@ } /** - * Less or equals. + * Less than or equals. + * + * Search if an element value is less than or equals to the parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put. + * @param value the value to be compared to. + * @return {@code this} with the {@code le} restriction added. */ public Search le(String element, String value) { restrictions.add(RestrictionHelper.lessEq(elt(element), value)); @@ -340,13 +407,15 @@ } /** - * Restrict search so that the element value is between lower and upper - * values (it can also be equals) + * Between. + * + * Restrict search so that the element value is between the lower and upper + * values (it can also be equals). * - * @param element the element you put the restriction on - * @param lowerValue the lower bound - * @param upperValue the upper bound - * @return {@code this} + * @param element the element on which the restriction is put. + * @param lowerValue the lower bound. + * @param upperValue the upper bound. + * @return {@code this} with the {@code le} restriction added. */ public Search bw(String element, String lowerValue, String upperValue) { restrictions.add(RestrictionHelper.between(elt(element), lowerValue, upperValue)); @@ -355,10 +424,12 @@ /** * Starts with. - * - * @param element - * @param value - * @return {@code this} + * + * Search if an element starts with the value in parameter. + * + * @param element the element on which the restriction is put. + * @param value the value the element must start with. + * @return {@code this} with the {@code sw} restriction added. */ public Search sw(String element, String value) { restrictions.add(RestrictionHelper.start(elt(element), value)); @@ -367,10 +438,12 @@ /** * Not starts with. + * + * Search if an element does not starts with the value in parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put. + * @param value the value the element must not start with. + * @return {@code this} with the {@code nsw} restriction added. */ public Search nsw(String element, String value) { restrictions.add(RestrictionHelper.not( @@ -380,10 +453,12 @@ /** * Ends with. + * + * Search if an element ends with the value in parameter. * - * @param element - * @param value - * @return {@code this} + * @param element the element on which the restriction is put + * @param value the value the element must ends with. + * @return {@code this} with the {@code ew} restriction added. */ public Search ew(String element, String value) { restrictions.add(RestrictionHelper.end(elt(element), value)); @@ -392,10 +467,12 @@ /** * Not ends with. - * - * @param element - * @param value - * @return {@code this} + * + * Search if an element does not ends with the value in parameter. + * + * @param element the element on which the restriction is put + * @param value the value the element must not ends with. + * @return {@code this} with the {@code notew} restriction added. */ public Search notew(String element, String value) { restrictions.add(RestrictionHelper.not( @@ -405,9 +482,12 @@ /** * Keyword. + * + * Search if the value in parameter is present in any field of any + * extension. * - * @param value - * @return {@code this} + * @param value the value to find. + * @return {@code this} with the {@code keyword} restriction added. */ public Search keyword(String value) { restrictions.add(RestrictionHelper.keyword(value)); @@ -417,8 +497,10 @@ /** * Is null. * - * @param fieldName - * @return {@code this} + * Check that a field is null. + * + * @param fieldName the field that must be null. + * @return {@code this} with the {@code isNull} restriction added. */ public Search isNull(String fieldName) { restrictions.add(RestrictionHelper.isNull(fieldName)); @@ -428,8 +510,10 @@ /** * Is not null. * - * @param fieldName - * @return {@code this} + * Check that a field is not null. + * + * @param fieldName the field that must not be null. + * @return {@code this} with the {@code isNotNull} restriction added. */ public Search isNotNull(String fieldName) { restrictions.add(RestrictionHelper.isNotNull(fieldName)); @@ -439,7 +523,9 @@ /** * False. * - * @return {@code this} + * Add a restriction that always return false. + * + * @return {@code this} with the {@code rFalse} restriction added. */ public Search rFalse() { restrictions.add(RestrictionHelper.rFalse()); @@ -449,7 +535,9 @@ /** * True. * - * @return {@code this} + * Add a restriction that always return true. + * + * @return {@code this} with the {@code rTrue} restriction added. */ public Search rTrue() { restrictions.add(RestrictionHelper.rTrue()); @@ -459,7 +547,10 @@ /** * Like. * - * @param element + * Check that a string is present in a field. For example "tric" is present + * in "Restriction". + * + * @param element the element on which the restriction is put * @param value * @param searchAs * @return {@code this} @@ -478,7 +569,7 @@ /** * Unlike. * - * @param element + * @param element the element on which the restriction is put * @param value * @param searchAs * @return {@code this} @@ -531,6 +622,11 @@ return search; } + /** + * + * @param foreignFieldName + * @return + */ public Search associated(String foreignFieldName) { Search search = new SubSearch(foreignFieldName, this); return search;