svn commit: r619354 - /incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java

[fm...@apache.org]

Author: fmeschbe
Date: Thu Feb  7 02:45:21 2008
New Revision: 619354

URL: http://svn.apache.org/viewvc?rev=619354&view=rev
Log:
SLING-234 reintroduce include(String, RequestDispatcherOptions) method and
enhance java doc

Modified:
    incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java

Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java?rev=619354&r1=619353&r2=619354&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java Thu Feb  7 02:45:21 2008
@@ -54,8 +54,8 @@
      * Same as {@link #include(String,RequestDispatcherOptions)}, but using
      * empty options.
      * 
-     * @trows SlingIOException Wrapping a <code>IOException</code> thrown
-     *        while handling the include.
+     * @throws SlingIOException Wrapping a <code>IOException</code> thrown
+     *             while handling the include.
      * @throws SlingServletException Wrapping a <code>ServletException</code>
      *             thrown while handling the include.
      */
@@ -63,11 +63,54 @@
 
     /**
      * Helper method to include the result of processing the request for the
-     * given <code>path</code>. This method is intended to be implemented as
+     * given <code>path</code> and <code>requestDispatcherOptions</code>.
+     * This method is intended to be implemented as follows:
+     * 
+     * <pre>
+     * RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path,
+     *     &quot;option:xyz&quot;);
+     * if (dispatcher != null) {
+     *     dispatcher.include(getRequest(), getResponse());
+     * }
+     * </pre>
+     * 
+     * <p>
+     * The request dispatcher options provided to this method as a string are
+     * internally parsed into an {@link RequestDispatcherOptions} object as
      * follows:
+     * <ul>
+     * <li>If the string neither contains a comma nor an equals sign, the
+     * string is assumed to be a resource type. Hence a
+     * <code>RequestDispatcherOptions</code> object is created with the
+     * {@link RequestDispatcherOptions#OPT_FORCE_RESOURCE_TYPE} field set to the
+     * string.</li>
+     * <li>Otherwise the string is assumed to be a comma separated list of name
+     * value pairs where the equals sign is used to separate the name from its
+     * value. Hence a <code>RequestDispatcherOptions</code> object is created
+     * from the name value pair list.</li>
+     * </ul>
+     * 
+     * @param path The path to the resource to include.
+     * @param requestDispatcherOptions influence the rendering of the included
+     *            Resource
+     * @throws SlingIOException Wrapping a <code>IOException</code> thrown
+     *             while handling the include.
+     * @throws SlingServletException Wrapping a <code>ServletException</code>
+     *             thrown while handling the include.
+     * @see RequestDispatcherOptions
+     * @see #include(String, RequestDispatcherOptions)
+     */
+    void include(String path, String requestDispatcherOptions);
+
+    /**
+     * Helper method to include the result of processing the request for the
+     * given <code>path</code> and <code>options</code>. This method is
+     * intended to be implemented as follows:
      * 
      * <pre>
-     * RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path);
+     * RequestDispatcherOptions opts = new RequestDispatcherOptions();
+     * opts.put(&quot;option&quot;, &quot;xyz&quot;);
+     * RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path, opts);
      * if (dispatcher != null) {
      *     dispatcher.include(getRequest(), getResponse());
      * }
@@ -75,11 +118,13 @@
      * 
      * @param path The path to the resource to include.
      * @param options influence the rendering of the included Resource
-     * @trows SlingIOException Wrapping a <code>IOException</code> thrown
-     *        while handling the include.
+     * @throws SlingIOException Wrapping a <code>IOException</code> thrown
+     *             while handling the include.
      * @throws SlingServletException Wrapping a <code>ServletException</code>
      *             thrown while handling the include.
+     * @see RequestDispatcherOptions
+     * @see #include(String, String)
      */
-    void include(String path, String requestDispatcherOptions);
+    void include(String path, RequestDispatcherOptions options);
 
 }