You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by fm...@apache.org on 2007/12/17 12:34:25 UTC
svn commit: r604836 - in
/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting:
SlingBindings.java SlingScript.java SlingScriptEngine.java
SlingScriptHelper.java SlingScriptResolver.java
Author: fmeschbe
Date: Mon Dec 17 03:34:24 2007
New Revision: 604836
URL: http://svn.apache.org/viewvc?rev=604836&view=rev
Log:
SLING-110 Refactor Sling API removing SlingScriptEngine and
adapting the other interfaces.
Added:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingBindings.java
Removed:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptEngine.java
Modified:
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptHelper.java
incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java
Added: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingBindings.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingBindings.java?rev=604836&view=auto
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingBindings.java (added)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingBindings.java Mon Dec 17 03:34:24 2007
@@ -0,0 +1,126 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.sling.api.scripting;
+
+import java.util.HashMap;
+
+/**
+ * The <code>SlingBindings</code> class is used to prepare global variables
+ * for script execution. The constants in this class define names of variables
+ * which <em>MUST</em> or <em>MAY</em> be provided for the script execution.
+ * Other variables may be define as callers see fit.
+ */
+public class SlingBindings extends HashMap<String, Object> {
+
+ /**
+ * The name of the global scripting variable providing the
+ * {@link org.apache.sling.api.SlingHttpServletRequest} object (value is
+ * "request"). The value of the scripting variable is the same as that
+ * returned by the
+ * {@link org.apache.sling.api.scripting.SlingScriptHelper#getRequest()}
+ * method.
+ * <p>
+ * This bound variable is required in the bindings given the script.
+ */
+ public static final String REQUEST = "request";
+
+ /**
+ * The name of the global scripting variable providing the
+ * {@link org.apache.sling.api.SlingHttpServletResponse} object (value is
+ * "response"). The value of the scripting variable is the same as that
+ * returned by the
+ * {@link org.apache.sling.api.scripting.SlingScriptHelper#getResponse()}
+ * method.
+ * <p>
+ * This bound variable is required in the bindings given the script.
+ */
+ public static final String RESPONSE = "response";
+
+ /**
+ * The name of the global scripting variable providing the
+ * {@link org.apache.sling.api.scripting.SlingScriptHelper} for the request
+ * (value is "sling").
+ * <p>
+ * This bound variable is optional. If existing, the script helper instance
+ * must be bound to the same request and response objects as bound with the
+ * {@link #REQUEST} and {@link #RESPONSE} variables. If this variable is not
+ * bound, the script implementation will create it before actually
+ * evaluating the script.
+ */
+ public static final String SLING = "sling";
+
+ /**
+ * The name of the global scripting variable providing the
+ * {@link org.apache.sling.api.resource.Resource} object (value is
+ * "resource"). The value of the scripting variable is the same as that
+ * returned by the <code>SlingScriptHelper.getRequest().getResource()</code>
+ * method.
+ * <p>
+ * This bound variable is optional. If existing, the resource must be bound
+ * to the same resource as returned by the
+ * <code>SlingHttpServletRequest.getResource()</code> method. If this
+ * variable is not bound, the script implementation will bind it before
+ * actually evaluating the script.
+ */
+ public static final String RESOURCE = "resource";
+
+ /**
+ * The name of the global scripting variable providing the
+ * <code>java.io.PrintWriter</code> object to return the response content
+ * (value is "out"). The value of the scripting variable is the same as that
+ * returned by the <code>SlingScriptHelper.getResponse().getWriter()</code>
+ * method.
+ * <p>
+ * Note, that it may be advisable to implement a lazy acquiring writer for
+ * the <em>out</em> variable to enable the script to write binary data to
+ * the response output stream instead of the writer.
+ * <p>
+ * This bound variable is optional. If existing, the resource must be bound
+ * to the same writer as returned by the
+ * <code>SlingHttpServletResponse.getWriter()</code> method of the
+ * response object bound to the {@link #RESPONSE} variable. If this variable
+ * is not bound, the script implementation will bind it before actually
+ * evaluating the script.
+ */
+ public static final String OUT = "out";
+
+ /**
+ * The name of the global scripting variable indicating whether the output
+ * used by the script should be flushed after the script evaluation ended
+ * normally (value is "flush").
+ * <p>
+ * The type of this variable is <code>java.lang.Boolean</code> indicating
+ * whether to flush the output (value is <code>TRUE</code>) or not (value
+ * is <code>FALSE</code>). If the variable has a non-<code>null</code>
+ * value of another type, the output is not flush as if the value would be
+ * <code>FALSE</code>.
+ */
+ public static final String FLUSH = "flush";
+
+ /**
+ * The name of the global scripting variable providing a logger which may be
+ * used for logging purposes (value is "log"). The logger provides the API
+ * defined by the SLF4J <code>org.slf4j.Logger</code> interface.
+ * <p>
+ * This bound variable is optional. If this variable is not bound, the
+ * script implementation will bind it before actually evaluating the script.
+ */
+ public static final String LOG = "log";
+
+}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java?rev=604836&r1=604835&r2=604836&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScript.java Mon Dec 17 03:34:24 2007
@@ -19,21 +19,23 @@
package org.apache.sling.api.scripting;
import java.io.IOException;
-import java.io.Reader;
+
+import javax.servlet.ServletException;
import org.apache.sling.api.resource.Resource;
/**
* The <code>SlingScript</code> defines the API for objects which encapsulate
* a script resolved by the {@link SlingScriptResolver}. To have a script
- * evaluated by its {@link SlingScriptEngine} prepare a
- * <code>Map<<String, Object></code> of properties used as top level
- * (global) variables to the script and call the
- * {@link SlingScriptEngine#eval(SlingScript, java.util.Map)} method.
+ * evaluated prepare a {@link SlingBindings} instance of variables used as
+ * global variables to the script and call the {@link #eval(SlingBindings)}
+ * method.
* <p>
* Objects implementing this interface are returned by the
* {@link SlingScriptResolver#resolveScript(org.apache.sling.api.SlingHttpServletRequest)}
- * method.
+ * and
+ * {@link SlingScriptResolver#findScript(org.apache.sling.api.resource.ResourceResolver, String)}
+ * methods.
*/
public interface SlingScript {
@@ -43,20 +45,20 @@
Resource getScriptResource();
/**
- * Returns the {@link SlingScriptEngine} used to evaluate this script.
+ * Evaluates this script using the bound variables as global variables to
+ * the script.
+ *
+ * @param props The {@link SlingBindings} providing the bound variables for
+ * evaluating the script. Any bound variables must conform to the
+ * requirements of the {@link SlingBindings} predefined variables
+ * set.
+ * @throws IOException if an input or output error occurrs.
+ * @throws ServletException if another error occurrs evaluating the script.
+ * The exception should encapsulate the error cause. This
+ * exception is also called if the <code>props</code>
+ * predefined bindings are not compliant with the definition in
+ * the {@link SlingBindings} class.
*/
- SlingScriptEngine getScriptEngine();
+ void eval(SlingBindings props) throws IOException, ServletException;
- /**
- * Returns a <code>java.io.Reader</code> from which the scripting engine
- * may read the script source to be evaluated.
- * <p>
- * The <code>Reader</code> returned need not be buffered. Any buffering
- * used for enhanced performance is expected to be implemented by consumers
- * of this method.
- *
- * @throws IOException If an error occurrs acquiring the <code>Reader</code>
- * for the script source.
- */
- Reader getScriptReader() throws IOException;
}
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=604836&r1=604835&r2=604836&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 Mon Dec 17 03:34:24 2007
@@ -29,7 +29,7 @@
/**
* The <code>SlingScriptHelper</code> interface defines the API of a helper
* class which is provided to the scripts called from sling through the global
- * <code>{@link SlingScriptEngine#SLING sling}</code> variable.
+ * <code>{@link SlingBindings#SLING sling}</code> variable.
*/
public interface SlingScriptHelper {
@@ -47,12 +47,18 @@
/**
* Returns the {@link SlingScript} being called to handle the request. This
- * is the same instance as given to the {@link SlingScriptEngine} for
- * evaluation.
+ * is the same instance as given to the {@link javax.script.ScriptEngine}
+ * for evaluation.
*/
SlingScript getScript();
/**
+ * Same as {@link #include(String,RequestDispatcherOptions)}, but using
+ * empty options.
+ */
+ void include(String path) throws ServletException, IOException;
+
+ /**
* Helper method to include the result of processing the request for the
* given <code>path</code>. This method is intended to be implemented as
* follows:
@@ -65,14 +71,11 @@
* </pre>
*
* @param path The path to the resource to include.
- * @param options influence the rendering of the included Resource
+ * @param options influence the rendering of the included Resource
* @throws ServletException Forwarded from including the resource
* @throws IOException Forwarded from including the resource
*/
- void include(String path,RequestDispatcherOptions options) throws ServletException, IOException;
+ void include(String path, RequestDispatcherOptions options)
+ throws ServletException, IOException;
- /** Same as {@link #include(String,RequestDispatcherOptions)}, but using
- * empty options.
- */
- void include(String path) throws ServletException, IOException;
}
Modified: incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java
URL: http://svn.apache.org/viewvc/incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java?rev=604836&r1=604835&r2=604836&view=diff
==============================================================================
--- incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java (original)
+++ incubator/sling/trunk/api/src/main/java/org/apache/sling/api/scripting/SlingScriptResolver.java Mon Dec 17 03:34:24 2007
@@ -18,6 +18,7 @@
import org.apache.sling.api.SlingException;
import org.apache.sling.api.SlingHttpServletRequest;
+import org.apache.sling.api.resource.ResourceResolver;
/**
* The <code>ScriptResolver</code> interface defines the API for a service
@@ -41,8 +42,8 @@
* through a <code>RequestDispatcher</code> is handled by the Sling Framework.
* <p>
* The servlet resolver service is available from the
- * {@link org.apache.sling.api.services.ServiceLocator} using the interface class as
- * parameter.
+ * {@link org.apache.sling.api.services.ServiceLocator} using the interface
+ * class as parameter.
*/
public interface SlingScriptResolver {
@@ -62,15 +63,18 @@
* Finds the given name to a {@link SlingScript}.
* <p>
* The semantic meaning of the name is implementation specific: It may be an
- * absolute path to a JCR respository Item providing the script source or it
- * may be a relative path resolved according to some path settings. Finally,
- * the name may also just be used as an itentifier to find the script in
- * some registry.
+ * absolute path to a <code>Resource</code> providing the script source or
+ * it may be a relative path resolved according to some path settings.
+ * Finally, the name may also just be used as an itentifier to find the
+ * script in some registry.
*
+ * @param resourceResolver The <code>ResourceResolver</code> used to
+ * access the script.
* @param name The script name. Must not be <code>null</code>.
* @return The {@link SlingScript} to which the name resolved or
* <code>null</code> otherwise.
* @throws SlingException If an error occurrs trying to resolve the name.
*/
- SlingScript findScript(String name) throws SlingException;
+ SlingScript findScript(ResourceResolver resourceResolver, String name)
+ throws SlingException;
}