Author: vmassol
Date: 2007-09-28 10:51:43 +0200 (Fri, 28 Sep 2007)
New Revision: 5121
Modified:
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/api/XWiki.java
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/store/XWikiStoreInterface.java
Log:
XWIKI-1770: Add new searchDocuments() API that accepts named HQL queries
* Added missing javadoc that I had forgotten
Modified:
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/api/XWiki.java
===================================================================
---
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/api/XWiki.java
2007-09-28 08:49:25 UTC (rev 5120)
+++
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/api/XWiki.java
2007-09-28 08:51:43 UTC (rev 5121)
@@ -464,6 +464,28 @@
return wrapDocs(xwiki.getStore().searchDocuments(wheresql, nb, start,
getXWikiContext()));
}
+ /**
+ * Search documents by passing HQL where clause values as parameters. This
allows generating
+ * a Named HQL query which will automatically encode the passed values
(like escaping single
+ * quotes). This API is recommended to be used over the other similar
methods where the values
+ * are passed inside the where clause and for which you'll need to do the
encoding/escpaing
+ * yourself before calling them.
+ *
+ * <p>Example</p>
+ * <pre><code>
+ * #set($orphans = $xwiki.searchDocuments(" where doc.fullName <> ? and
(doc.parent = ? or "
+ * + "(doc.parent = ? and doc.web = ?))",
+ * ["${doc.fullName}as", ${doc.fullName}, ${doc.name}, ${doc.web}]))
+ * </code></pre>
+ *
+ * @param parametrizedSqlClause the HQL where clause. For example <code>"
where doc.fullName
+ * <> ? and (doc.parent = ? or (doc.parent = ? and doc.web = ?))"
+ * @param nb the number of rows to return. If 0 then all rows are returned
+ * @param start the number of rows to skip. If 0 don't skip any row
+ * @param parameterValues the where clause values that replace the
question marks (?)
+ * @return a list of document names
+ * @throws XWikiException in case of error while performing the query
+ */
public List searchDocuments(String parametrizedSqlClause, int nb, int
start,
List parameterValues) throws XWikiException
{
@@ -471,6 +493,11 @@
parameterValues, getXWikiContext());
}
+ /**
+ * Same as [EMAIL PROTECTED] #searchDocuments(String, int, int,
java.util.List)} but returns all rows.
+ *
+ * @see #searchDocuments(String, int, int, java.util.List)
+ */
public List searchDocuments(String parametrizedSqlClause, List
parameterValues)
throws XWikiException
{
Modified:
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/store/XWikiStoreInterface.java
===================================================================
---
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/store/XWikiStoreInterface.java
2007-09-28 08:49:25 UTC (rev 5120)
+++
xwiki-platform/core/trunk/xwiki-core/src/main/java/com/xpn/xwiki/store/XWikiStoreInterface.java
2007-09-28 08:51:43 UTC (rev 5121)
@@ -40,8 +40,42 @@
public List searchDocumentsNames(String wheresql, XWikiContext context)
throws XWikiException;
public List searchDocumentsNames(String wheresql, int nb, int start,
XWikiContext context) throws XWikiException;
public List searchDocumentsNames(String wheresql, int nb, int start,
String selectColumns, XWikiContext context) throws XWikiException;
- public List searchDocumentsNames(String parametrizedSqlClause, int nb, int
start, List parameterValues, XWikiContext context) throws XWikiException;
- public List searchDocumentsNames(String parametrizedSqlClause, List
parameterValues, XWikiContext context) throws XWikiException;
+
+ /**
+ * Search documents by passing HQL where clause values as parameters. This
allows generating
+ * a Named HQL query which will automatically encode the passed values
(like escaping single
+ * quotes). This API is recommended to be used over the other similar
methods where the values
+ * are passed inside the where clause and for which you'll need to do the
encoding/escpaing
+ * yourself before calling them.
+ *
+ * <p>Example</p>
+ * <pre><code>
+ * #set($orphans = $xwiki.searchDocuments(" where doc.fullName <> ? and
(doc.parent = ? or "
+ * + "(doc.parent = ? and doc.web = ?))",
+ * ["${doc.fullName}as", ${doc.fullName}, ${doc.name}, ${doc.web}]))
+ * </code></pre>
+ *
+ * @param parametrizedSqlClause the HQL where clause. For example <code>"
where doc.fullName
+ * <> ? and (doc.parent = ? or (doc.parent = ? and doc.web = ?))"
+ * @param nb the number of rows to return. If 0 then all rows are returned
+ * @param start the number of rows to skip. If 0 don't skip any row
+ * @param parameterValues the where clause values that replace the
question marks (?)
+ * @param context the XWiki context required for getting information about
the execution context
+ * @return a list of document names
+ * @throws XWikiException in case of error while performing the query
+ */
+ public List searchDocumentsNames(String parametrizedSqlClause, int nb, int
start,
+ List parameterValues, XWikiContext context) throws XWikiException;
+
+ /**
+ * Same as [EMAIL PROTECTED] #searchDocumentsNames(String, int, int, List,
XWikiContext)} but returns all
+ * rows.
+ *
+ * @see #searchDocumentsNames(String, int, int, java.util.List,
com.xpn.xwiki.XWikiContext)
+ */
+ public List searchDocumentsNames(String parametrizedSqlClause, List
parameterValues,
+ XWikiContext context) throws XWikiException;
+
public List searchDocuments(String wheresql, boolean distinctbyname,
XWikiContext context) throws XWikiException;
public List searchDocuments(String wheresql, boolean distinctbyname,
boolean customMapping, XWikiContext context) throws XWikiException;
public List searchDocuments(String wheresql, boolean distinctbyname, int
nb, int start, XWikiContext context) throws XWikiException;
_______________________________________________
notifications mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/notifications
