| <!-- |
| 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. |
| --> |
| |
| |
| #Navigation Top |
| [<<Back to the Start Page](./index.html) |
| or |
| [On to the Openwebbeans Spring Guide >>](./owbSpring.html) |
| |
| #General information |
| This page covers the general installation and integration process, it does not |
| go into the details of the configuration. |
| The section covers the setup via download or custom build. If you need configuration detail info |
| or information on how to setup your ide correctly please follow the links in the navigation to |
| the correct section. |
| |
| #Setup overview |
| ## General Setup Information |
| |
| Ext-Scripting has a complete appendix list over all [configuration and |
| setup](./configentries.html) options as well as [example configurations](./exampleconfig.html). |
| For a quick overview please visit the following links. If you need detailed |
| setup information, then read further on. |
| |
| |
| ## Links |
| |
| <ul><a href="./setupSteps.html">Appendix: Configuration Setup Step Overview</a> </ul> |
| <ul><a href="./exampleconfig.html">Appendix: Example Configurations</a> </ul> |
| <ul><a href="./configentries.html">Appendix: List of Configuration Options</a> </ul> |
| |
| |
| |
| #Checklist |
| |
| For a short checklist of setup steps please follow [ this link](./setupSteps.html). For a detailed |
| setup guide, please continue reading. |
| |
| |
| #Download |
| |
| With version 1.0.x Ext-Scripting provides all necessary artifacts |
| as download artifacts to get quickly started. |
| A kickstart project is provided which can be used as shell for your own |
| projects. |
| |
| |
| For Download information please visit the [ download page](./download.html). |
| |
| |
| Once you downloaded the necessary artifacts please check the [manual setup section](#Manual_Setup) of this document. |
| |
| |
| #Checkout and Build |
| |
| While Ext-Scripting is already in stable state, the best way to get started |
| is probably to checkout and build Ext-Scripting yourself from the latest codebase. |
| All other installation steps will have this step as prerequisite if you want to |
| use the latest codebase instead of one of the beta releases! |
| First you have to check out the latest codebase from |
| [ |
| http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk |
| ](http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk) |
| via a subversion client. |
| |
| |
| Make sure you have following requirements fulfilled before checking out: |
| |
| <ul> |
| <li>A valid Subversion client</li> |
| <li>A valid Servlet 3.0+ container</li> |
| <li>Java 6 or higher</li> |
| <li>Maven 2.0.9 or higher</li> |
| </ul> |
| |
| 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 started viamvn jetty:run-exploded. |
| The now generated files either can be used to be included in a maven install or be included manually |
| (please go to the next section for detailed setup instructions) |
| |
| |
| #Setup of Ext-Scripting |
| ## Requirements |
| |
| Before setting up Ext-Scripting for your project make sure following requirements are met. |
| |
| <ul> |
| <li>JAVA_HOME points towards a valid Java SDK (JRE is not sufficient)</li> |
| <li>You know how to create and deploy a web application within your preferred setup (command line, |
| ide) |
| </li> |
| </ul> |
| |
| ## 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. |
| |
| <ul> |
| <li>A valid |
| <b>MyFaces</b> |
| installation has to be present |
| </li> |
| <li>Ext-Scripting and its dependencies has to be added to the MyFaces installation</li> |
| <li>The paths to the scripts have to be present (see also below)</li> |
| </ul> |
| |
| ## Preparations via Apache Maven 2 |
| The easiest way once Extension scripting is compiled is probably a setup via Apache Maven 2 |
| |
| |
| Depending on your configuration and preferred JDK version you can add following entries to your |
| Maven pom.xml to enable Ext-Scripting |
| |
| |
| MyFaces 2.1+ |
| <dependency> |
| <groupId>org.apache.myfaces.extensions.scripting</groupId> |
| <artifactId>extscript-myfaces20-bundle</artifactId> |
| <version>1.0.5</version> |
| </dependency> |
| Additional language libraries |
| |
| You have to add following artifacts to your dependency list for additional language support |
| <dependency> |
| <groupId>org.codehaus.groovy</groupId> |
| <artifactId>groovy-all</artifactId> |
| <version>1.7.1</version> |
| </dependency> |
| |
| For Groovy support (version number may vary) |
| <dependency> |
| <groupId>org.scala-lang</groupId> |
| <artifactId>scala-library</artifactId> |
| <version>2.9.1</version> |
| </dependency> |
| <dependency> |
| <groupId>org.scala-lang</groupId> |
| <artifactId>scala-compiler</artifactId> |
| <version>2.9.1</version> |
| </dependency> |
| |
| For Scala support. |
| |
| For OpenWebbeans support please add following entry: |
| <dependency> |
| <groupId>org.apache.myfaces.extensions.scripting</groupId> |
| <artifactId>extscript-cdi</artifactId> |
| <version>1.0.5</version> |
| </dependency> |
| |
| |
| |
| ## Manual Setup |
| If you do not like Maven or you prefer a manual setup, Ext-Scripting provides convenient meta bundles. |
| A manual setup |
| comes down to the task of adding the appropriate meta bundle (extscript-myfaces20-bundle) |
| to your WEB-INF/lib directory and adding a groovy-all.jar as additional dependency. |
| For Scala support you have to add scala-library.jar and scala-compiler.jar to your |
| WEB-INFU/lib. Note not adding those additional libs automatically will disable |
| the respective language support. |
| |
| you can obtain both bundle jars after the build from: |
| <ul> |
| <li><yourbuilderoot>/extscript-bundles/extscript-myfaces20-bundle/target/extscript-myfaces20-bundle-1.0.3-SNAPSHOT.jar</li> |
| </ul> |
| The additional language jars for the respective language |
| can be obtained from the language distributions. |
| |
| |
| However following dependencies must be met so that Ext-Scripting can work: |
| <ul> |
| <li>commons-beanutils.jar version 1.8.3 or above</li> |
| <li>commons-codec.jar version 1.3 or above</li> |
| <li>commons-collections.jar version 3.2 or above</li> |
| <li>commons-io.jar version 1.4 or above</li> |
| <li>commons-logging.jar version 1.1.1 or above</li> |
| <li>commons-digester version 1.8 or above</li> |
| <li>groovy-all.jar version 1.7.2 or above</li> |
| <li>scala-compiler.jar version 2.10.0-M2 or above</li> |
| <li>scala-library.jar version 2.10.0-M2 or above</li> |
| </ul> |
| For your convenience an empty webapp is provided within the [download page](./download.html) |
| which delivers all needed dependencies to get you kickstarted. |
| |
| After having done that you are ready to setup the rest of the Ext-Scripting configuration manually as |
| described in the section blow |
| |
| |
| ## Preparing the Necessary web.xml Entries |
| Most important step |
| To enable Ext-Scripting you also have to add several entries to your web.xml file. |
| First a context param has to be set which attaches the Ext-Scripting plugins to 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> |
| Additional Optional Steps |
| Ext-Scripting exposes a number configuration parameters which can be set via context parameters in |
| your web.xml |
| |
| Adjust the web.xml Root source paths. |
| Since the goal of Ext-Scripting is to provide scriptability to a running web application, it has to |
| know where to find the sources. 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. |
| |
| |
| Following image displays the default locations: |
|  |
| |
| 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.extensions.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.extensions.scripting.java.LOADER_PATHS</param-name> |
| <param-value> |
| <some project path>/src/main/webapp/WEB-INF/java |
| </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.extensions.scripting.scala.LOADER_PATHS</param-name> |
| <param-value> |
| <some project path>/src/main/webapp/WEB-INF/scala |
| </param-value> |
| </context-param> |
| |
| <ul> |
| <li> |
| <b>org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS</b> |
| can be a comma separated list of paths which point to the actual Groovy sources. |
| </li> |
| <li> |
| <b>org.apache.myfaces.extensions.scripting.java.LOADER_PATHS</b> |
| does the same for Java sources.. |
| </li> |
| <li> |
| <b>org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS</b> |
| does the same for Java Scala (Ext-Scripting 1.0.3 or newer)... |
| </li> |
| </ul> |
| Dynamic resource reloading |
| Additionally Ext-Scripting allows the reloading of dynamic web resources |
| like Facelets templates images css files etc... An additional config param is |
| available to enable this functionality. |
| |
| |
| <ul> |
| <li> |
| <b>org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS</b> |
| This parameter points to the root of your dynamic resources, usually the same dir |
| as the root of your web application. |
| </li> |
| <li><b>facelets.RESOURCE_RESOLVER</b> also needs to be set to <b>org.apache.myfaces.extensions.scripting.jsf.facelet.ReroutingResourceResolver</b> if |
| you want dynamic Facelet reloading enabled</li> |
| </ul> |
| <!-- ====================================================================================== |
| Optional Loader Paths for resource files |
| ====================================================================================== --> |
| <context-param> |
| <description>resource paths for our custom JSF2 resource resolver</description> |
| <param-name>org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS</param-name> |
| <param-value> |
| ~/extensions-scripting3/examples/myfaces20-example/src/main/webapp |
| </param-value> |
| </context-param> |
| <!-- ====================================================================================== |
| Optional: Tell Facelets to load the resources from your source dir |
| ====================================================================================== --> |
| <context-param> |
| <description>a redirecting Facelet resource resolver which allows to pick up templates |
| and resources from our source dir |
| </description> |
| <param-name>facelets.RESOURCE_RESOLVER</param-name> |
| <param-value>org.apache.myfaces.extensions.scripting.jsf.facelet.ReroutingResourceResolver</param-value> |
| </context-param> |
| |
| |
| This sums up the quick install and setup guide, if you want more detailed setup examples and |
| additional configuration entries |
| go to our [Example Configurations](./exampleconfig.html) page, which shows |
| a set of different configurations. |
| Package Whitelisting |
| The last possible config entry is the ability to whitelist packages. If you have set this option |
| then only whitelisted packages will be picked up for dynamic recompilation |
| With this option you can point your source dir to the normal compile source and mark |
| special packages as dynamic (to isolate the dynamic part from the rest) |
| To enable this option, add following entry to your web.xml: |
| <!-- ====================================================================================== |
| Optional: Whitelist of root packages where your sources should come from |
| ====================================================================================== --> |
| <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.extensions.scripting.PGK_WHITELIST</param-name> |
| <param-value>org.apache.myfaces.groovyloader.blog,org.apache.myfaces.javaloader.blog</param-value> |
| </context-param> |
| |
| |
| ## Preparations for Openwebbeans |
| From a Ext-Scripting perspective, dropping the extscript-cdi war into your libraries dir |
| is enough to enable Openwebbeans support, however you have to have Openwebbeans installed properly |
| which means you have to add a beans.xml file to your META-INF directory and you have to add following |
| entry to your web.xml file: |
| <!-- ======================================================================================== |
| Optional: enable only if you have openwebbeans working |
| ========================================================================================== --> |
| <listener> |
| <listener-class>org.apache.webbeans.servlet.WebBeansConfigurationListener</listener-class> |
| </listener> |
| |
| |
| |
| |
| #Navigation Bottom |
| [<<Back to the Start Page](./index.html) |
| or |
| [On to the Openwebbeans Spring Guide >>](./owbSpring.html) |
| |
| |
