Table of Contents

Setup Extensions Scripting

Checkout and Build

Currently as time of writing, Ext-Scripting does not have a release yet, so the only means of obtaining a build is checking out the project via

via the svn trunk

Make sure you have following requirements fulfilled before checking out:

  • A valid svn client
  • Java 5 or higher
  • Maven 2.0.9 or higher

After checkout, a full build can be obtained from the root directory of your checkout via mvn clean install.

Once finished, a valid build is installed, which can be used further on. Additionally you can find two blueprint projects which you can use as starting points for your own projects under <checkoutDir>/examples which can be kickstarted via mvn jetty:run-exploded

Setup of Ext-Scripting

Requirements

Before setting up Ext-Scripting make sure following requirements are met.

  • JAVA_HOME points towards a valid Java SDK (JRE is not sufficient)
  • You know how to create and deploy a web application within your preferred setup (command line, ide)

Setup

While one of the aims of Ext-Scripting was to enable an easy setup, for now it was not entirely possible for now to get a plug and play configuration. Several configuration steps have to be performed.

  • A valid <<<MyFaces>>> installation has to be present
  • Ext-Scripting and its dependencies has to be added to the myfaces installation
  • Several entries in the web.xml have to be added (see below)
  • The paths to the scripts have to be present (see also below)

Setup via maven

The easiest way once Extension scripting is compiled is probably a setup via maven (once a release is out the compile step can be skipped)

Depending on your configuration and preferred JDK version you can add following entries to your Maven pom.xml to enable Ext-Scripting

        <dependency>
            <groupId>org.apache.myfaces.extension-scripting</groupId>
            <artifactId>extscript-myfaces12-bundle</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>

       <dependency>
           <groupId>org.apache.myfaces.extension-scripting</groupId>
           <artifactId>extscript-myfaces20-bundle</artifactId>
           <version>1.0-SNAPSHOT</version>
       </dependency>

web.xml MyFaces Plugin Loader

<<<EXT-SCRIPTING>>> relies on an existing plugin extension point of MyFaces.

    <context-param>
        <description>
            Enables our scripting engine support plugins
        </description>
        <param-name>org.apache.myfaces.FACES_INIT_PLUGINS</param-name>
        <param-value>org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader</param-value>
    </context-param>

This parameter and the servlet filter <<<MUST>>> be set otherwise ext-scripting will not be enabled!

web.xml Filter

Ext-Scripting relies on several entries to be present in the web.xml to function properly.

    <filter>
       <filter-name>scriptingFilter</filter-name>
       <filter-class>org.apache.myfaces.extensions.scripting.servlet.ScriptingServletFilter</filter-class>
    </filter>
    <filter-mapping>
       <filter-name>scriptingFilter</filter-name>
       <url-pattern>*.jsf</url-pattern>
    </filter-mapping>

You can also map the filter directly to the Faces Servlet

       <servlet-name>faces</servlet-name>

Make sure to map the filter to the correct url-pattern or servlet-name otherwise ext-scripting will not be enabled!

When you see the following error in your logs (and probably a NullPointerException stack trace), check your filter configuration. You probably have an error in your filter configuration.

WARNING: [EXT-SCRIPTING] Scripting Weaver is not set. Disabling script reloading subsystem. Make sure you have the scripting servlet filter enabled in your web.xml

web.xml Root Sourcepaths

Since the goal of Ext-Scripting is to provide scriptability to a running web application it has to know where to find the sources it has to process. For this a default location has been chosen according to the standards set by the Mojarra Groovy extension the location looks like:

   <webapp>/WEB-INF/groovy

as root location for Groovy files

    <webapp>/WEB-INF/java

as root location for java files.

However in a normal development scenario, it is often undesirable to have the files located in a deployment location, and a pointer mechanism towards the actual source locations would be more desirable.

To provide such a mechanism, Ext-Scripting allows two optional web.xml context parameters, which allow the rerouting of source locations of the supported languages!

   <context-param>
        <description>Additional comma separated loader paths to allow direct editing on the sources directory instead
            of the deployment dir
        </description>
        <param-name>org.apache.myfaces.scripting.groovy.LOADER_PATHS</param-name>
        <param-value>
           <some project path>/src/main/webapp/WEB-INF/groovy
        </param-value>
    </context-param>
    <context-param>
        <description>Additional comma separated loader paths to allow direct editing on the sources directory instead
            of the deployment dir
        </description>
        <param-name>org.apache.myfaces.scripting.java.LOADER_PATHS</param-name>
        <param-value>
            <some project path>/src/main/webapp/WEB-INF/java
        </param-value>
    </context-param>
  • <org.apache.myfaces.scripting.groovy.LOADER_PATHS> can be a comma separated list of paths which point to the actual Groovy sources.
  • <org.apache.myfaces.scripting.java.LOADER_PATHS> does the same for Java sources.

Setup of the Optional Resource and Page Reloading from the Source Directory

Ext-Scripting has an optional feature which allows resource and page reloading directly from the source directory without redeployment. To enable this it provides several hooks into the underlying frameworks, for Facelets a new resource loader is provided, which optionally can be enabled and for JSF2 an optional resource handler (disabled by default) is provided which also does the same for resources.

Following web.xml entries allow the enabling of this functionality:

  • facelets.RESOURCE_RESOLVER has to be set to org.apache.myfaces.extensions.scripting.facelet.ReroutingResourceResolver
  • org.apache.myfaces.scripting.resources.LOADER_PATHS has to be set to the location where the resource directory for your JSF2 resources is hosted! In a Maven project, this is typically the src/main/webapp directory. (don't forget to specify an absolute path!)
  • Additionally if you are in a JSF2 environment it is advicable that javax.faces.PROJECT_STAGE is set to Development to disable any resource caching

Note, the resource loading is only available in a JSF2 environment, if you need a similar functionality you can use one of the many available resource frameworks for instance Weblets

Setup of Whitelisted Packages

<<<Ext-Scripting>>> allows to define a subset of packages the system should react to. This is useful when you work on your entire source codebase without separate ext-scripting source directories, but if you only want to have ext-scripting reload the parts you really work on.

The result is a better speed and less interference with other systems (like proxying systems or javaagents)

To use this feature following web.xml context parameter has to be set:

   <context-param>
        <description>a comma separated whitelist of root packages which are compiled those and nothing else
            will be compiled during all compile stages, all other files stay permanently as they are
        </description>
        <param-name>org.apache.myfaces.scripting.PGK_WHITELIST</param-name>
        <param-value>comma.separated.list.of.packages</param-value>
    </context-param>

a comma separated list of whitelisted packages can be provided to exclude parts of your system from being handled by ext-scripting.

<<<Note if you use this feature make sure the parts of your system which are not handled by Ext-Scripting are precompiled by your build system>>>

Additional Classpaths

Although <<<EXT-SCRIPTING>>> uses internally the mechanisms the underlying container provides, and thus has full access to the classpath of the running application, it is sometimes desirable to add additinal jars and paths which the compiler needs for the processing of the source files.

Here the optional <<<org.apache.myfaces.scripting.ADDITIONAL_CLASSPATH>>> parameter helps out. With it you can add a comma separated list of additional classpath entries which are picked up at compile time.

   <context-param>
        <description>a comma separated whitelist of root packages which are compiled those and nothing else
            will be compiled during all compile stages, all other files stay permanently as they are
        </description>
        <param-name>org.apache.myfaces.scripting.ADDITIONAL_CLASSPATH</param-name>
        <param-value>/myDir/entry1.jar,/myDir/classes/</param-value>
    </context-param>
  • No labels