src/site/mdtext/install102.mdtext - myfaces-scripting - Git at Google

 <!--
     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
  [&lt;&lt;Back to the Start Page](./index.html)
  or
  [On to the General Users Guide&gt;&gt;](./usingGeneral.html)

 #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.

 #Setup overview
 ## General Setup Information

  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.


 ## Links

 <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>


 #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 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 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
  [
  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>Java 5 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
  &lt;checkoutDir&gt;/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 1.2.8+
          <dependency>
             <groupId>org.apache.myfaces.extensions.scripting</groupId>
             <artifactId>extscript-myfaces12-bundle</artifactId>
             <version>1.0-SNAPSHOT</version>
          </dependency>
  MyFaces 2.+
          <dependency>
             <groupId>org.apache.myfaces.extensions.scripting</groupId>
             <artifactId>extscript-myfaces20-bundle</artifactId>
             <version>1.0-SNAPSHOT</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-myfaces12-bundle or
  extscript-myfaces20-bundle)
  to your WEB-INF/lib directory and adding a groovy-all.jar as additional dependency.

  you can obtain both jars after the build from:
 <ul>
    <li>&lt;yourbuilderoot&gt;/extscript-bundles/extscript-myfaces12-bundle/target/extscript-myfaces12-bundle-1.0-SNAPSHOT.jar</li>
    <li>&lt;yourbuilderoot&gt;/extscript-bundles/extscript-myfaces20-bundle/target/extscript-myfaces20-bundle-1.0-SNAPSHOT.jar</li>
 </ul>

  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
  First 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>
  Second Step
  Add Ext-Scriptings servlet filter to your servlet configuration
         <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>
  The init parameter and the servlet filter
  MUST
  be set otherwise Ext-Scripting will not be enabled!

  For the filter pattern you can use every pattern which enables your web pages,
  the standard cases are, either *.jsf or /faces/*
  Note you must use the same pattern as described in the configuration
  part of your Faces Servlet.
  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:
  ![](images/ext-default-file.jpg)

  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>

 <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>


 #Navigation Bottom
  [&lt;&lt;Back to the Start Page](./index.html)
  or
  [On to the General Users Guide&gt;&gt;](./usingGeneral.html)
	<!--
	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 General Users Guide>>](./usingGeneral.html)

	#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.

	#Setup overview
	## General Setup Information

	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.


	## Links

	<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>



	#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 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 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
	[
	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>Java 5 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 1.2.8+
	<dependency>
	<groupId>org.apache.myfaces.extensions.scripting</groupId>
	<artifactId>extscript-myfaces12-bundle</artifactId>
	<version>1.0-SNAPSHOT</version>
	</dependency>
	MyFaces 2.+
	<dependency>
	<groupId>org.apache.myfaces.extensions.scripting</groupId>
	<artifactId>extscript-myfaces20-bundle</artifactId>
	<version>1.0-SNAPSHOT</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-myfaces12-bundle or
	extscript-myfaces20-bundle)
	to your WEB-INF/lib directory and adding a groovy-all.jar as additional dependency.

	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>

	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
	First 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>
	Second Step
	Add Ext-Scriptings servlet filter to your servlet configuration
	<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>
	The init parameter and the servlet filter
	MUST
	be set otherwise Ext-Scripting will not be enabled!

	For the filter pattern you can use every pattern which enables your web pages,
	the standard cases are, either .jsf or /faces/
	Note you must use the same pattern as described in the configuration
	part of your Faces Servlet.
	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:
	![](images/ext-default-file.jpg)

	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>

	<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>


	#Navigation Bottom
	[<<Back to the Start Page](./index.html)
	or
	[On to the General Users Guide>>](./usingGeneral.html)