Author: woonsan
Date: Wed Jul 21 01:55:48 2010
New Revision: 966066
URL: http://svn.apache.org/viewvc?rev=966066&view=rev
Log:
PB-104: Adding documentation for bridges-script.
Added:
portals/site/bridges/src/site/resources/images/scriptload.png (with props)
portals/site/bridges/src/site/xdoc/bridges-script/
portals/site/bridges/src/site/xdoc/bridges-script/index.xml (with props)
Modified:
portals/site/bridges/src/site/site.xml
portals/site/bridges/src/site/xdoc/index.xml
Added: portals/site/bridges/src/site/resources/images/scriptload.png
URL:
http://svn.apache.org/viewvc/portals/site/bridges/src/site/resources/images/scriptload.png?rev=966066&view=auto
==============================================================================
Binary file - no diff available.
Propchange: portals/site/bridges/src/site/resources/images/scriptload.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Modified: portals/site/bridges/src/site/site.xml
URL:
http://svn.apache.org/viewvc/portals/site/bridges/src/site/site.xml?rev=966066&r1=966065&r2=966066&view=diff
==============================================================================
--- portals/site/bridges/src/site/site.xml (original)
+++ portals/site/bridges/src/site/site.xml Wed Jul 21 01:55:48 2010
@@ -47,14 +47,15 @@
</menu>
<menu name="Current Portals Bridges">
<item name="Common Utilities and Interfaces"
href="bridges-common/index.html"/>
- <item name="Groovy Bridge" href="bridges-groovy/index.html"
collapse="true">
- <item name="Groovy PreferencesValidator Guide"
href="bridges-groovy/prefvalidate.html" />
- <item name="Jetspeed HeaderPhase Support Guide"
href="bridges-groovy/headersupport.html" />
- </item>
<item name="Struts Bridge" href="bridges-struts/index.html"
collapse="true">
<item name="Features" href="bridges-struts/features.html"/>
</item>
<item name="Velocity Bridge" href="bridges-velocity/index.html"/>
+ <item name="Script Bridge" href="bridges-script/index.html" />
+ <item name="Groovy Bridge" href="bridges-groovy/index.html"
collapse="true">
+ <item name="Groovy PreferencesValidator Guide"
href="bridges-groovy/prefvalidate.html" />
+ <item name="Jetspeed HeaderPhase Support Guide"
href="bridges-groovy/headersupport.html" />
+ </item>
</menu>
<menu name="Archived Portals Bridges">
<item name="JSF Bridge" href="bridges-jsf/index.html" collapse="true">
Added: portals/site/bridges/src/site/xdoc/bridges-script/index.xml
URL:
http://svn.apache.org/viewvc/portals/site/bridges/src/site/xdoc/bridges-script/index.xml?rev=966066&view=auto
==============================================================================
--- portals/site/bridges/src/site/xdoc/bridges-script/index.xml (added)
+++ portals/site/bridges/src/site/xdoc/bridges-script/index.xml Wed Jul 21
01:55:48 2010
@@ -0,0 +1,439 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+-->
+<document>
+ <properties>
+ <title>Script Bridget Portlet Guide</title>
+ <subtitle>Documentation for Creating a Script Bridget Portlet</subtitle>
+ <authors>
+ <person name="Woonsan Ko" email="[email protected]" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Script Bridget Portlet Guide">
+ <p>
+ This guide provides a tutorial for creating portlets with
+ <a href="http://www.jcp.org/en/jsr/detail?id=223";
target="_nw">JSR-223</a>
+ compliant scripting languages.
+ </p>
+ <subsection name="1. The ScriptPortlet">
+ <p>
+ The <CODE>ScriptPortlet</CODE>
(<CODE>org.apache.portals.bridges.script.ScriptPortlet</CODE>) is the bridge
portlet
+ which evaluates the scripted portlet source to initialize a portlet
instance
+ and dispatch each invocation to the scripted portlet instance.
+ </p>
+ <p>
+ In the portlet descriptor (portlet.xml), the
<CODE>ScriptPortlet</CODE> is provided as portlet-class.
+ The <CODE>ScriptPortlet</CODE> is configured with some init
parameters for script sources
+ which implement the real portlet or the real portlet preferences
validator.
+ </p>
+ <p>
+ <img src="../images/scriptload.png" />
+ <br/>
+ <ol>
+ <li>The <CODE>ScriptPortlet</CODE> initializes a
<CODE>ScriptEngine</CODE> based on either engine name or the type of the script
source.</li>
+ <li>
+ The <CODE>ScriptPortlet</CODE> evaluates the script source to
load a scripted portlet.
+ If script preferences validator is also configured, it evaluates
the validator script source to load a scripted preferences validator.
+ </li>
+ <li>
+ The <CODE>ScriptEngine</CODE> returns an evaluated object to the
<CODE>ScriptPortlet</CODE>.
+ Now, the <CODE>ScriptPortlet</CODE> dispatches all the
invocations to the script objects.
+ <br/>
+ The evaluated object from the portlet script source must be
either a <CODE>javax.portlet.Portlet</CODE> instance or a
<CODE>javax.portlet.Portlet</CODE> class.
+ <br/>
+ Also, the evaluated object from the portlet script preferences
validator must be either a <CODE>javax.portlet.PreferencesValidator</CODE>
instance or a <CODE>javax.portlet.PreferencesValidator</CODE> class.
+ </li>
+ </ol>
+ </p>
+ <p>
+ With the <CODE>ScriptPortlet</CODE> bridge portlet, you can just
provide your script sources.
+ The <CODE>ScriptPortlet</CODE> will care everything to create
<CODE>ScriptEngine</CODE> and to use your script codes.
+ </p>
+ </subsection>
+ <subsection name="2. Scripted 'Hello World!' Portlets with Groovy,
JRuby, Jython, BeanShell and Rhino JavaScript">
+ <p>If you use a script language which is <a
href="http://www.jcp.org/en/jsr/detail?id=223"; target="_nw">JSR-223</a>
+ compliant, then you can implement full-featured portlets with the
script language.</p>
+ <p>Here are "Hello, World!" example portlets implemented by Groovy,
JRuby, Jython, BeanShell or Rhino JavaScript. You can choose any.</p>
+
+ <h4>Groovy example</h4>
+ <p>
+ In this example, <CODE>HelloGroovy.groovy</CODE> implements a simple
portlet in Groovy.
+ </p>
+ <p>
+ <strong>Note:</strong> The last statement creates a portlet instance
to be passed
+ to the <CODE>ScriptPortlet</CODE> as script evaluation result via
the <CODE>ScriptEngine</CODE>.
+ </p>
+ <p>
+ <source><![CDATA[
+import javax.portlet.GenericPortlet;
+import javax.portlet.ActionRequest;
+import javax.portlet.ActionResponse;
+import javax.portlet.EventRequest;
+import javax.portlet.EventResponse;
+import javax.portlet.RenderRequest;
+import javax.portlet.RenderResponse;
+import javax.portlet.ResourceRequest;
+import javax.portlet.ResourceResponse;
+
+/**
+ * HelloGroovy.groovy
+ */
+public class HelloGroovy extends GenericPortlet
+{
+ public void doView(RenderRequest request, RenderResponse response)
+ {
+ String greeting = "<H1>Hello, Groovy!</H1>";
+ response.getWriter().println(greeting);
+ }
+}
+
+// Return portlet instance as a last evaluated object
+// because ScriptPortlet expects the evaluated result object
+// as a portlet class or non-initialized portlet instance.
+new HelloGroovy();
+ ]]></source>
+ </p>
+
+ <h4>JRuby example</h4>
+ <p>
+ In this example, <CODE>HelloJRuby.rb</CODE> implements a simple
portlet in JRuby.
+ </p>
+ <p>
+ <strong>Note:</strong> The last statement creates a portlet instance
to be passed
+ to the <CODE>ScriptPortlet</CODE> as script evaluation result via
the <CODE>ScriptEngine</CODE>.
+ </p>
+ <p>
+ <source><![CDATA[
+require 'java'
+
+#
+# HelloJRuby.rb
+#
+class HelloJRuby < javax.portlet.GenericPortlet
+
+ def doView(request, response)
+ greeting = "<H1>Hello, JRuby!</H1>"
+ response.writer.println(greeting)
+ end
+
+end
+
+# Return portlet instance as a last evaluated object
+# because ScriptPortlet expects the evaluated result object
+# as a portlet class or non-initialized portlet instance.
+HelloJRuby.new
+ ]]></source>
+ </p>
+
+ <h4>Jython example</h4>
+ <p>
+ In this example, <CODE>HelloJython.py</CODE> implements a simple
portlet in Jython.
+ </p>
+ <p>
+ <strong>Note:</strong> The last statement creates a portlet instance
to be passed
+ to the <CODE>ScriptPortlet</CODE> as script evaluation result via
the <CODE>ScriptEngine</CODE>.
+ </p>
+ <p>
+ <source><![CDATA[
+from javax.portlet import GenericPortlet
+
+#
+# HelloJython.py
+#
+class HelloJython(GenericPortlet):
+ def doView(self, request, response):
+ greeting = "<H1>Hello, Jython!</H1>"
+ response.writer.println(greeting)
+
+
+
+# Return portlet instance as a last evaluated object
+# because ScriptPortlet expects the evaluated result object
+# as a portlet class or non-initialized portlet instance.
+value = HelloJython()
+ ]]></source>
+ </p>
+
+ <h4>BeanShell example</h4>
+ <p>
+ In this example, <CODE>HelloBeanShell.bsh</CODE> implements a simple
portlet in BeanShell.
+ </p>
+ <p>
+ <strong>Note:</strong> The last statement creates a portlet instance
to be passed
+ to the <CODE>ScriptPortlet</CODE> as script evaluation result via
the <CODE>ScriptEngine</CODE>.
+ </p>
+ <p>
+ <source><![CDATA[
+import javax.portlet.GenericPortlet;
+import javax.portlet.ActionRequest;
+import javax.portlet.ActionResponse;
+import javax.portlet.EventRequest;
+import javax.portlet.EventResponse;
+import javax.portlet.RenderRequest;
+import javax.portlet.RenderResponse;
+import javax.portlet.ResourceRequest;
+import javax.portlet.ResourceResponse;
+
+/**
+ * HelloBeanShell.bsh
+ */
+class HelloBeanShell extends GenericPortlet
+{
+ public void doView(RenderRequest request, RenderResponse response)
+ {
+ String greeting = "<H1>Hello, BeanShell!</H1>";
+ response.getWriter().println(greeting);
+ }
+}
+
+// Return portlet instance as a last evaluated object
+// because ScriptPortlet expects the evaluated result object
+// as a portlet class or non-initialized portlet instance.
+new HelloBeanShell();
+ ]]></source>
+ </p>
+
+ <h4>Rhino JavaScript example</h4>
+ <p>
+ In this example, <CODE>HelloRhino.js</CODE> implements a simple
portlet in Rhino JavaScript.
+ </p>
+ <p>
+ <strong>Note:</strong> The last statement creates a portlet instance
to be passed
+ to the <CODE>ScriptPortlet</CODE> as script evaluation result via
the <CODE>ScriptEngine</CODE>.
+ </p>
+ <p>
+ <source><![CDATA[
+importPackage(Packages.javax.portlet);
+
+/**
+ * HelloRhino.js
+ */
+
+// Return portlet instance as a last evaluated object
+// because ScriptPortlet expects the evaluated result object
+// as a portlet class or non-initialized portlet instance.
+new GenericPortlet(
+ {
+ doView: function(request, response) {
+ greeting = "<H1>Hello, Rhino JavaScript!</H1>";
+ response.getWriter().println(greeting);
+ }
+ }
+);
+ ]]></source>
+ </p>
+ </subsection>
+ <subsection name="3. The portlet.xml">
+ <p>Edit your portlet.xml like the following example.</p>
+ <p>Please refer to the comments on each init parameter for details.</p>
+ <p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<portlet-app id="velocitysimplest" version="1.0">
+
+ <portlet>
+ <portlet-name>HelloGroovy</portlet-name>
+ <display-name>Hello Groovy</display-name>
+
<portlet-class>org.apache.portals.bridges.script.ScriptPortlet</portlet-class>
+
+ <!-- Optional init parameter for script engine
+ If this init parameter is not set, the ScriptPortlet will look up a script
engine automatically
+ by the mimeType or the extension of the script source file. -->
+ <init-param>
+ <name>engine</name>
+ <!--
+ Note: You can set other script engine which support JSR-223
ScriptEngine
+ such as 'groovy', 'jruby', 'jython'.
+ -->
+ <value>groovy</value>
+ </init-param>
+
+ <!-- Optional init parameter for the key for portlet/preferencesValidator
class or
+ portlet/preferencesValidator instance which is evaluated and returned by
the script.
+ By default, when this init parameter is not set, ScriptPortlet retrieves
+ the last evaluated object from the script.
+ If you set this to 'value', then ScriptPortlet retrieves an object named
'value'
+ from the bindings of the script engine.
+ Depending on script engines, this init parameter should be properly
configured
+ because some script engines do not return the last evaluated object. -->
+ <init-param>
+ <name>eval-key</name>
+ <value>value</value>
+ </init-param>
+
+ <!-- Required init parameter for script source path -->
+ <init-param>
+ <name>source</name>
+ <!--
+ Note: You can set script source in three ways.
+ The first is to use context relative path,
+ the second is to use file: url,
+ and the third is to classpath: uri.
+ Here are the examples for each way.
+ -->
+ <!--
+ <value>/WEB-INF/groovy/HelloGroovy.groovy</value>
+ <value>file:/C:/Program
Files/Tomcat/webapps/demo/WEB-INF/groovy/HelloGroovy.groovy</value>
+
<value>classpath:org/apache/portals/bridges/script/HelloGroovy.groovy</value>
+ -->
+
<value>classpath:org/apache/portals/bridges/script/HelloGroovy.groovy</value>
+ </init-param>
+
+ <!-- Optional init parameter for script file content encoding. The default
value is 'UTF-8'. -->
+ <init-param>
+ <name>encoding</name>
+ <value>UTF-8</value>
+ </init-param>
+
+ <!-- Optional init parameter for auto-refresh option.
+ If auto-refresh is true, then a modification of script source can be
refreshed automatically.
+ By default, this option is set to false. -->
+ <init-param>
+ <name>auto-refresh</name>
+ <value>true</value>
+ </init-param>
+
+ <!-- Optional init parameter for refresh-delay option.
+ When auto-refresh is true, this init parameter sets the milliseconds of
automatic refreshing interval.
+ By default, this option is set to 60000 milliseconds (a minute). -->
+ <init-param>
+ <name>refresh-delay</name>
+ <value>60000</value>
+ </init-param>
+
+ <!-- Optional init parameter for script preferences validator path -->
+ <init-param>
+ <name>validator</name>
+ <!--
+ Note: You can set script preferences validator source in three ways.
+ The first is to use context relative path,
+ the second is to use file: url,
+ and the third is to classpath: uri.
+ Here are the examples for each way.
+ -->
+ <!--
+ <value>/WEB-INF/groovy/HelloGroovyPrefsValidator.groovy</value>
+ <value>file:/C:/Program
Files/Tomcat/webapps/demo/WEB-INF/groovy/HelloGroovyPrefsValidator.groovy</value>
+
<value>classpath:org/apache/portals/bridges/script/HelloGroovyPrefsValidator.groovy</value>
+ -->
+
<value>classpath:org/apache/portals/bridges/script/HelloGroovyPrefsValidator.groovy</value>
+ </init-param>
+
+ <!-- The followings are not special for ScriptPortlet, but normal
configurations for a portlet. -->
+ <supports>
+ <mime-type>text/html</mime-type>
+ <portlet-mode>VIEW</portlet-mode>
+ <portlet-mode>EDIT</portlet-mode>
+ <portlet-mode>HELP</portlet-mode>
+ </supports>
+ <supported-locale>en</supported-locale>
+ <portlet-info>
+ <title>Hello Groovy</title>
+ <short-title>Hello Groovy</short-title>
+ <keywords>demo,groovy</keywords>
+ </portlet-info>
+ <portlet-preferences>
+ <preference>
+ <name>message</name>
+ <value>Hello, Groovy!</value>
+ </preference>
+
<preferences-validator>org.apache.portals.bridges.script.ScriptPortletPreferencesValidator</preferences-validator>
+ </portlet-preferences>
+
+ </portlet>
+
+</portlet-app>]]>
+ </source>
+ </p>
+ </subsection>
+ <subsection name="4. The Dependency JARs">
+ <p>
+ For simplicity, the following dependencies are provided for each
script language.
+ </p>
+ <h4>For Groovy Portlet Developers</h4>
+ <p>You can add the following dependency only in your project to use
<CODE>ScriptPortlet</CODE> with your preferred script langauge.</p>
+ <p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.portals.bridges</groupId>
+ <artifactId>portals-bridges-script-dependencies-groovy</artifactId>
+ <version>2.0</version>
+</dependency>
+ ]]></source>
+ </p>
+ <h4>For JRuby Portlet Developers</h4>
+ <p>You can add the following dependency only in your project to use
<CODE>ScriptPortlet</CODE> with your preferred script langauge.</p>
+ <p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.portals.bridges</groupId>
+ <artifactId>portals-bridges-script-dependencies-jruby</artifactId>
+ <version>2.0</version>
+</dependency>
+ ]]></source>
+ </p>
+ <h4>For Jython Portlet Developers</h4>
+ <p>You can add the following dependency only in your project to use
<CODE>ScriptPortlet</CODE> with your preferred script langauge.</p>
+ <p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.portals.bridges</groupId>
+ <artifactId>portals-bridges-script-dependencies-jython</artifactId>
+ <version>2.0</version>
+</dependency>
+ ]]></source>
+ </p>
+ <h4>For BeanShell Portlet Developers</h4>
+ <p>You can add the following dependency only in your project to use
<CODE>ScriptPortlet</CODE> with your preferred script langauge.</p>
+ <p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.portals.bridges</groupId>
+ <artifactId>portals-bridges-script-dependencies-beanshell</artifactId>
+ <version>2.0</version>
+</dependency>
+ ]]></source>
+ </p>
+ <h4>For Rhino JavaScript Portlet Developers</h4>
+ <p>You can add the following dependency only in your project to use
<CODE>ScriptPortlet</CODE> with your preferred script langauge.</p>
+ <p>
+ <source><![CDATA[
+<dependency>
+ <groupId>org.apache.portals.bridges</groupId>
+ <artifactId>portals-bridges-script-dependencies-rhino</artifactId>
+ <version>2.0</version>
+</dependency>
+ ]]></source>
+ </p>
+ </subsection>
+ <subsection name="5. Deploy the WAR file">
+ <p>
+ After building the war file, copy the war file of your portlet
application to
+ <code>$CATALINA_HOME/webapps/jetspeed/WEB-INF/deploy/</code>.
+ Jetspeed-2 will deploy your portlet application automatically.
+ </p>
+ </subsection>
+ <subsection name="6. The PSML">
+ <p>
+ Add your script portlet into a portal page.
+ You must have the permission to add portlets into the page.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: portals/site/bridges/src/site/xdoc/bridges-script/index.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: portals/site/bridges/src/site/xdoc/bridges-script/index.xml
------------------------------------------------------------------------------
svn:keywords = Id
Modified: portals/site/bridges/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/portals/site/bridges/src/site/xdoc/index.xml?rev=966066&r1=966065&r2=966066&view=diff
==============================================================================
--- portals/site/bridges/src/site/xdoc/index.xml (original)
+++ portals/site/bridges/src/site/xdoc/index.xml Wed Jul 21 01:55:48 2010
@@ -26,8 +26,8 @@ limitations under the License.
<body>
<section name="Overview">
<p>
- Portals Bridges provides support for <a
href="http://www.jcp.org/en/jsr/detail?id=168"; target="_nw">JSR-168</a>
compliant
- Portlet development using common web frameworks like Struts, JSF, PHP,
Perl, Velocity and Groovy.
+ Portals Bridges provides support for <a
href="http://www.jcp.org/en/jsr/detail?id=168"; target="_nw">JSR-168</a> or <a
href="http://www.jcp.org/en/jsr/detail?id=286"; target="_nw">JSR-286</a>
compliant
+ Portlet development using common web frameworks like Struts, JSF, PHP,
Perl, Velocity and Scripts such as Groovy, JRuby, Jython, BeanShell or Rhino
JavaScript.
</p>
<subsection name="JavaServer Faces">
<p>
@@ -120,12 +120,21 @@ limitations under the License.
Portlets, together with a library of useful scripts.
</p>
</subsection>
+ <subsection name="Script">
+ <p>
+ The <a href="bridges-script/index.html">Script Portlet Bridge</a>
allows using any <a href="http://www.jcp.org/en/jsr/detail?id=223";
target="_nw">JSR-223</a>
+ compliant scripting languages such as Groovy, JRuby, Jython, BeanShell
or Rhino JavaScript for rapid portlet development.
+ A script portlet can be implemented as a class just like Java-based
portlets, and so developers can use any techniques used in Java.
+ For example, a script portlet can extend
org.apache.portals.bridges.common.GenericServletPortlet to simplify
implementation.
+ Therefore, ScriptPorlet is very simple, but it will be very useful for
script developers.
+ </p>
+ </subsection>
<subsection name="Groovy">
<p>
The <a href="bridges-groovy/index.html">Groovy Portlet Bridge</a>
allows using groovy scripting for rapid portlet development.
A groovy script portlet can be implemented like Java-based portlets,
and so developers can use any techniques used in Java.
For example, a groovy script portlet can extend
org.apache.portals.bridges.common.GenericServletPortlet to simplify
implementation.
- Therefore, GroovyPortlet is very simple, but it will be very useful
for developers.
+ Therefore, GroovyPortlet is very simple, but it will be very useful
for groovy developers.
</p>
</subsection>
<subsection name="Perl">
