svn commit: r1505617 - in /felix/site/trunk/content/documentation/subprojects: apache-felix-script-console-plugin.mdtext script-console-1.png

[ch...@apache.org]

Author: chetanm
Date: Mon Jul 22 08:03:10 2013
New Revision: 1505617

URL: http://svn.apache.org/r1505617
Log:
FELIX-4122 - Felix Script Console Plugin

Adding documentation

Added:
    felix/site/trunk/content/documentation/subprojects/apache-felix-script-console-plugin.mdtext
    felix/site/trunk/content/documentation/subprojects/script-console-1.png   (with props)

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-script-console-plugin.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-script-console-plugin.mdtext?rev=1505617&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-script-console-plugin.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-script-console-plugin.mdtext Mon Jul 22 08:03:10 2013
@@ -0,0 +1,137 @@
+Title: Apache Felix Script Console Plugin
+
+<div class="note">
+Work in progress as part of FELIX-4122
+</div>
+
+Script Console is a Felix web console plugin which allows evaluation of scripts within the OSGi container. It provides following
+features
+
+* Support evaluation of script in any  e.g. Groovy, JavaScript, Ruby etc. You would need to ensure that relevant language bundle is deployed
+* Code editor with syntax highlighting support based on [CodeMirror](http://codemirror.net/) Javascript library
+* Hot key support
+* Execute remote testcase via evaluating test scripts
+
+A collection of useful scripts is maintained in [this gist](https://gist.github.com/3748614)
+
+
+### Installation
+Untill the bundle is released you would need to build it and deploy
+
+### Usage
+After installing it you would see a new tab "Script Console" in [Felix Web Console](http://localhost:4502/system/console).
+The plugin screen provides a textarea to author script code. One can select the language via the given dropdown. The generated
+output is shown in pane below.
+
+The script exposes following variables
+* `request` - Current HttpServletRequest instance
+* `response` - Current HttpServletResponse instance
+* `reader` - Direct access to the Reader of the request - same as request.getReader(). Use it for reading the data of an HTTP request body.
+* `out` - Direct access to the PrintWriter of the response - same as response.getWriter(). Use it for writing to the HTTP response body.
+* `osgi` -  Provides convenience methods for scripts, mainly osgi.getService(foo.bar.Service.class) to retrieve OSGi services available in
+   OSGi Container (Class notation depending on scripting language).
+* `bundleContext` - OSGi BundleContext instance for the script console plugin bundle. Can be used to access the OSGi runtime
+
+So simplest script that can work is
+
+    :::groovy
+    out.println ("Hello world!!");
+
+To access a service use `osgi.getService`
+
+    :::groovy
+    def httpService = osgi.getService(org.osgi.service.http.HttpService.class)
+
+To access a service satisfying OSGi filter
+
+    :::groovy
+    def eventPlugin = osgi.getServices(javax.servlet.Servlet.class,'(felix.webconsole.label=events)')[0]
+
+
+Following hotkeys work
+* Ctrl+F9 - Execute the script
+* Ctrl+q - Clear the output
+
+To try out Groovy scripts just install the [Groovy Bundle](http://repo1.maven.org/maven2/org/codehaus/groovy/groovy-all/1.8.6/groovy-all-1.8.6.jar)
+
+### HTTP API
+The plugin can also be invoked by making POST request. It supports following parameters
+
+* `code`- Script content. Can be norm form data or a multi part content
+* `lang` - Language extension.
+    * Groovy - groovy
+    * JavaScript - esp
+
+If any exception occurs while evaluating the script then it would return the exception message with status set to 500. Scripts can control what output they want to emit.
+
+### Screenshots
+
+<img src="script-console-1.png">
+
+
+### Sample Scripts
+
+Following are some sample scripts in Groovy. Note the scripts might be depending on implementation details to access the
+relevant data structures
+
+1. Script to find out servlets which are registered problematically with Felix HTTP Service
+
+    :::groovy
+    import org.osgi.service.http.HttpService
+    import org.osgi.framework.FrameworkUtil
+    import org.osgi.framework.Bundle
+
+    def httpService = osgi.getService(HttpService.class)
+    httpService.handlerRegistry.aliasMap.each{alias,servlet ->
+        Bundle bnd = FrameworkUtil.getBundle(servlet.class)
+        println "$alias : ${servlet.class.name} ($bnd.symbolicName)"
+    }
+
+2. Script to load a class which is not exported and then invoke some static method on that class
+
+At times you need to access some private class to see the runtime state.
+
+    :::groovy
+    import org.osgi.framework.Bundle
+    import org.osgi.framework.BundleContext
+
+    //Script to load a class which is not exported and then invoke some static method on that class
+
+    //Name of the class
+    def className = "org.apache.sling.engine.impl.SlingMainServlet"
+
+    def resPath = className.replaceAll('.','/')+".class"
+    def bundles = bundleContext.getBundles().findAll{Bundle b ->
+        b.getEntry(resPath) != null
+    }
+
+    if(!bundles){
+       println "No bundle found for class $className"
+       return
+    }
+
+    def b = bundles.asList().first()
+    def clazz = b.loadClass(className)
+
+    //Invoke some static method
+    def result = clazz.metaClass.invokeStaticMethod(clazz, 'foo',  arg1)
+    println result
+
+3. Script to find out which bundle embeds a given class
+
+    :::groovy
+    import org.osgi.framework.Bundle
+    import org.osgi.framework.BundleContext
+
+    //Name of the class
+    def className = "org.apache.sling.engine.impl.SlingMainServlet"
+
+    def resPath = className.replaceAll('.','/')+".class"
+    def bundles = bundleContext.getBundles().findAll{Bundle b ->
+        b.getEntry(resPath) != null
+    }
+
+    println "Following bundles have the class"
+    bundles.each{
+        println it
+    }
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/script-console-1.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/script-console-1.png?rev=1505617&view=auto
==============================================================================
Binary file - no diff available.

Propchange: felix/site/trunk/content/documentation/subprojects/script-console-1.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream