| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| <!-- |
| 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>Installation</title> |
| </properties> |
| |
| <body> |
| <section name="Navigation Top"> |
| <a href="./index.html"><<Back to the Start Page</a> |
| or |
| |
| <a href="./usingGeneral.html">On to the General Users Guide>></a> |
| </section> |
| |
| <section name="General information"> |
| This page covers the general installation and integration process of Apache MyFaces Extension scripting |
| 1.0.2 or earlier,it does not go into the details of the configuration. |
| As of ext-script 1.0.3 a number of legacy dependencies are dropped for easier maintainability such as |
| |
| <ul> |
| <li>Support for Java 5 and earlier</li> |
| <li>Support for MyFaces 1.2.x</li> |
| <li>Support for Servlet 2.5 and earlier</li> |
| </ul> |
| |
| If you need to use Ext-Scripting with one of those configurations stick to 1.0.2. |
| |
| The section covers the setup via download or custom build. If you need configuration detail info |
| or info on how to setup your ide correctly please follow the links in the navigation to |
| the correct section. |
| |
| </section> |
| |
| |
| <section name="Setup overview"> |
| <subsection name="General Setup Information" > |
| <p> |
| |
| Ext-Scripting has a complete appendix list over all configuration and setup options |
| for a quick overview please visit the following links. If you need detailed |
| setup information, then read further on. |
| </p> |
| </subsection> |
| <subsection name="Links"> |
| <p> |
| <ul><a href="./setupSteps.html">Appendix: Configuration Setup Steps</a> </ul> |
| <ul><a href="./exampleconfig102.html">Appendix: Example Configurations for 1.0.2 or earlier</a> |
| </ul> |
| <ul><a href="./configentries102.html">Appendix: List of Configuration Options for 1.02 or earlier</a> </ul> |
| </p> |
| </subsection> |
| </section> |
| |
| |
| <section name="Checklist"> |
| <p> |
| |
| For a short checklist of setup steps please follow <b><a href="./setupSteps.html"> this link</a></b>. For a detailed |
| setup guide, please continue reading. |
| </p> |
| </section> |
| |
| |
| <section name="Download"> |
| <p> |
| With version 1.0 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. |
| </p> |
| <p> |
| For Download information please visit the <a href="./download.html"> download page</a>. |
| </p> |
| <p> |
| Once you downloaded the necessary artifacts please check the <a href="#Manual_Setup">manual setup section</a> of this document. |
| </p> |
| </section> |
| |
| <section name="Checkout and Build"> |
| <p> |
| While Ext-Scripting is already in beta stage, 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 |
| |
| <a href="http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk"> |
| http://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk |
| </a> |
| |
| via a subversion client. |
| </p> |
| <p> |
| Make sure you have following requirements fulfilled before checking out: |
| </p> |
| <ul> |
| <li>A valid Subversion client</li> |
| <li>Java 5 or higher</li> |
| <li>Maven 2.0.9 or higher</li> |
| </ul> |
| <p> |
| After checkout, a full build can be obtained from the root directory of your checkout via <b>mvn |
| clean install</b>. |
| </p> |
| <p> |
| 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 |
| <b><checkoutDir>/examples</b> |
| , which can be started via<b>mvn jetty:run-exploded</b>. |
| 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) |
| |
| </p> |
| |
| </section> |
| |
| <section name="Setup of Ext-Scripting"> |
| |
| <subsection name="Requirements"> |
| <p> |
| Before setting up Ext-Scripting for your project make sure following requirements are met. |
| </p> |
| <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> |
| </subsection> |
| |
| <subsection name="Setup"> |
| <p> |
| 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. |
| </p> |
| <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> |
| |
| </subsection> |
| |
| |
| <subsection name="Preparations via Apache Maven 2"> |
| <p>The easiest way once Extension scripting is compiled is probably a setup via Apache Maven 2 |
| </p> |
| <p> |
| Depending on your configuration and preferred JDK version you can add following entries to your |
| Maven pom.xml to enable Ext-Scripting |
| </p> |
| |
| <p> </p> |
| <h4>MyFaces 1.2.8+</h4> |
| <source><![CDATA[ |
| <dependency> |
| <groupId>org.apache.myfaces.extensions.scripting</groupId> |
| <artifactId>extscript-myfaces12-bundle</artifactId> |
| <version>1.0-SNAPSHOT</version> |
| </dependency>]]></source> |
| |
| <h4>MyFaces 2.+</h4> |
| <source><![CDATA[ |
| <dependency> |
| <groupId>org.apache.myfaces.extensions.scripting</groupId> |
| <artifactId>extscript-myfaces20-bundle</artifactId> |
| <version>1.0-SNAPSHOT</version> |
| </dependency>]]></source> |
| </subsection> |
| |
| |
| <subsection name="Manual Setup"> |
| <p>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-myfaces12-bundle or |
| extscript-myfaces20-bundle) |
| to your WEB-INF/lib directory and adding a groovy-all.jar as additional dependency. |
| </p> |
| <p>you can obtain both jars after the build from: |
| <ul> |
| <li><yourbuilderoot>/extscript-bundles/extscript-myfaces12-bundle/target/extscript-myfaces12-bundle-1.0-SNAPSHOT.jar</li> |
| <li><yourbuilderoot>/extscript-bundles/extscript-myfaces20-bundle/target/extscript-myfaces20-bundle-1.0-SNAPSHOT.jar</li> |
| </ul> |
| </p> |
| <p>After having done that you are ready to setup the rest of the Ext-Scripting configuration manually as |
| described in the section blow |
| </p> |
| </subsection> |
| |
| |
| <subsection name="Preparing the Necessary web.xml Entries"> |
| <h4>First Step</h4> |
| <p>To enable Ext-Scripting you also have to add several entries to your web.xml file.</p> |
| |
| <p>First a context param has to be set which attaches the Ext-Scripting plugins to MyFaces</p> |
| <source><![CDATA[ |
| <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>]]></source> |
| <h4>Second Step</h4> |
| <p>Add Ext-Scriptings servlet filter to your servlet configuration</p> |
| <source><![CDATA[ |
| <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> |
| <dispatcher>REQUEST</dispatcher> |
| <dispatcher>FORWARD</dispatcher> |
| <dispatcher>INCLUDE</dispatcher> |
| <dispatcher>ERROR</dispatcher> |
| </filter-mapping>]]></source> |
| <p>The init parameter and the servlet filter |
| <b>MUST</b> |
| be set otherwise Ext-Scripting will not be enabled! |
| </p> |
| <p> For the filter pattern you can use every pattern which enables your web pages, |
| the standard cases are, either <b>*.jsf</b> or <b>/faces/*</b> |
| Note you <b>must</b> use the same pattern as described in the configuration |
| part of your Faces Servlet.</p> |
| <h4>Additional Optional Steps</h4> |
| <p>Ext-Scripting exposes a number configuration parameters which can be set via context parameters in |
| your web.xml |
| </p> |
| |
| <h4>Adjust the web.xml Root source paths.</h4> |
| <p>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. |
| </p> |
| <p> |
| The location looks like: |
| </p> |
| <source><![CDATA[ |
| <webapp>/WEB-INF/groovy |
| ]]></source> |
| <p> |
| as root location for Groovy files |
| </p> |
| <source><![CDATA[ |
| <webapp>/WEB-INF/java |
| ]]></source> |
| <p> |
| as root location for java files. |
| </p> |
| <p> |
| Following image displays the default locations: |
| <img src="images/ext-default-file.jpg"/> |
| </p> |
| <p>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! |
| </p> |
| <source><![CDATA[ |
| <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> |
| ]]></source> |
| <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> |
| </ul> |
| |
| </subsection> |
| </section> |
| |
| <section name="Navigation Bottom"> |
| <a href="./index.html"><<Back to the Start Page</a> |
| or |
| |
| <a href="./usingGeneral.html">On to the General Users Guide>></a> |
| </section> |
| |
| </body> |
| </document> |
| |
