[Openutils-svn] SF.net SVN: openutils:[1260] trunk/openutils-mgnlcriteria/src/main/java/net /sourceforge/openutils/mgnlcriteria/jcr/query/Criteria.java

[<fg...@us...>]

Revision: 1260
          http://openutils.svn.sourceforge.net/openutils/?rev=1260&view=rev
Author:   fgrilli
Date:     2009-08-13 08:42:22 +0000 (Thu, 13 Aug 2009)

Log Message:
-----------
improced javadoc for Criteria

Modified Paths:
--------------
    trunk/openutils-mgnlcriteria/src/main/java/net/sourceforge/openutils/mgnlcriteria/jcr/query/Criteria.java

Modified: trunk/openutils-mgnlcriteria/src/main/java/net/sourceforge/openutils/mgnlcriteria/jcr/query/Criteria.java
===================================================================
--- trunk/openutils-mgnlcriteria/src/main/java/net/sourceforge/openutils/mgnlcriteria/jcr/query/Criteria.java	2009-08-13 08:10:16 UTC (rev 1259)
+++ trunk/openutils-mgnlcriteria/src/main/java/net/sourceforge/openutils/mgnlcriteria/jcr/query/Criteria.java	2009-08-13 08:42:22 UTC (rev 1260)
@@ -26,7 +26,6 @@
 
 
 /**
- * 
  * <tt>Criteria</tt> is a simplified API for retrieving JCR Nodes by composing <tt>Criterion</tt> objects. This is a
  * very convenient approach for functionality like "search" screens where there is a variable number of conditions to be
  * placed upon the result set.<br>
@@ -52,12 +51,57 @@
  *  //dogs//*[((jcr:contains(@name, 'Nana')) and (@weight&gt;10.0) and (@birthDate &gt;=xs:dateTime('2004-01-01T00:00:00.000+00:00') and @birthDate &lt;=xs:dateTime('2008-12-01T23:59:59.000+00:00')))] order by @name descending
  * </pre>
  * 
- * A word of warning about implementations returned by JCRCriteriaFactory. They are <strong>NOT</strong> thread-safe, therefore client
- * code wishing to use one of them as a shared global variable <strong>MUST</strong> coordinate access to it. These objects are actually
- * meant to be instantiated and used within a method scope (e.g. a service method), where no concurrent issues arise. <br>
+ * You can also specify a different type to be returned in the Collection of results. eg.
+ * 
+ * <pre>
+ * Collection&lt;Pet&gt; pets = JCRCriteriaFactory.createMgnlCriteria("//dogs//*", MgnlContext.getQueryManager("website"), "mgnl:content", Pet.class).add(
+ *      Restrictions.contains("@name", "Nana")).add(
+ *      Restrictions.gt("@weight", new Float(10))).add(
+ *      Restrictions.between("@birthDate", begin, end).addOrder(
+ *      Order.desc("@name")).list();
+ * </pre>
+ * 
+ * Internally, this will use info.magnolia.content2bean.Content2BeanUtil.toBean() to transform nodes into beans. So, for
+ * example, if you have a domain Pet class like this
+ * 
+ * <pre>
+ * public class Pet
+ * {
+ *  private String name;
+ *  private Float weight;
+ *  private Calendar birthDate;
+ *  //getters and setters here...
+ * }
+ * </pre>
+ * 
+ * Content nodes returned by the above query will be automatically converted to and populate instances of the
+ * <code>Pet</code> type. Furthermore, you may want to have only a subset of the whole result set returned, much like in
+ * a MySQL limit clause. In this case, you will use the <code>JCRCriteriaFactory.createMgnlCriteriaWithLimit</code> factory method.
+ * For this to work, the underlying JCR repository implementation must support this feature (Jackrabbit 1.4+ does). Here
+ * is an example.
+ * 
+ *<pre>
+ * Collection&lt;Pet&gt; pets = JCRCriteriaFactory.createMgnlCriteriaWithLimit("//dogs//*", MgnlContext.getQueryManager("website"), "mgnl:content", Pet.class).add(
+ *      Restrictions.contains("@name", "Nana")).add(
+ *      Restrictions.gt("@weight", new Float(10))).add(
+ *      Restrictions.between("@birthDate", begin, end).
+ *      setFirstResult(5).
+ *      setMaxResults(10).
+ *      addOrder(Order.desc("@jcr:score()")).list();
+ *</pre>
+ * 
+ * Notice the <code>setFirstResult(int)</code> and <code>setMaxResults(int)</code> methods. Now calling
+ * <code>list()</code> will return a subset of only five <code>Pet</code> objects, starting from the 6th item (counting
+ * starts from 0). If you dont specify these two calls, <code>list()</code> will behave as usual by returning the entire result set.
+ * If you only call <code>setMaxResults(int)</code>, the result set will be the subset of elements <code>[0, maxResults]</code>
+ * (firstResultValue is 0 by default). 
+ * <br><br>
+ * A word of warning about implementations returned by <code>JCRCriteriaFactory</code>. They are <strong>NOT</strong> thread-safe,
+ * therefore client code wishing to use one of them as a shared global variable <strong>MUST</strong> coordinate access
+ * to it. These objects are actually meant to be instantiated and used within a method scope (e.g. a service method),
+ * where no concurrent issues arise. <br>
  * <br>
- * This API was inspired by Hibernate's Criteria API. <br>
- * 
+ * This API was inspired by Hibernate's Criteria API. <br><br>
  * @see JCRCriteriaFactory#createMgnlCriteria(String, info.magnolia.cms.core.search.QueryManager, String)
  * @see JCRCriteriaFactory#createMgnlCriteria(String, info.magnolia.cms.core.search.QueryManager, String, Class)
  * @see JCRCriteriaFactory#createMgnlCriteriaWithLimit(String, info.magnolia.cms.core.search.QueryManager, String)


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.