From 6462c727b8570e9b8a74d604b4cfe578222e6308 Mon Sep 17 00:00:00 2001 From: Werner Punz Date: Wed, 31 Oct 2012 11:07:11 +0000 Subject: [PATCH] https://issues.apache.org/jira/browse/EXTSCRIPT-179 adding the generated mdtext files to the site git-svn-id: https://svn.apache.org/repos/asf/myfaces/extensions/scripting/trunk@1404090 13f79535-47bb-0310-9956-ffa450edef68 --- .gitignore | 1 - src/site/mdtext/configentries.mdtext | 112 ++++++ src/site/mdtext/configentries102.mdtext | 132 +++++++ src/site/mdtext/exampleconfig.mdtext | 172 ++++++++++ src/site/mdtext/exampleconfig102.mdtext | 183 ++++++++++ src/site/mdtext/index.mdtext | 84 +++++ src/site/mdtext/install102.mdtext | 260 ++++++++++++++ src/site/mdtext/installation.mdtext | 362 ++++++++++++++++++++ src/site/mdtext/issuetracking.mdtext | 6 + src/site/mdtext/setupSteps.mdtext | 56 +++ src/site/mdtext/usersguide.mdtext | 77 +++++ src/site/mdtext/usingAdvanced.mdtext | 437 ++++++++++++++++++++++++ src/site/mdtext/usingEclipse.mdtext | 56 +++ src/site/mdtext/usingGeneral.mdtext | 40 +++ src/site/mdtext/usingIntellij.mdtext | 65 ++++ src/site/mdtext/usingNetbeans.mdtext | 72 ++++ 16 files changed, 2114 insertions(+), 1 deletion(-) create mode 100644 src/site/mdtext/configentries.mdtext create mode 100644 src/site/mdtext/configentries102.mdtext create mode 100644 src/site/mdtext/exampleconfig.mdtext create mode 100644 src/site/mdtext/exampleconfig102.mdtext create mode 100644 src/site/mdtext/index.mdtext create mode 100644 src/site/mdtext/install102.mdtext create mode 100644 src/site/mdtext/installation.mdtext create mode 100644 src/site/mdtext/issuetracking.mdtext create mode 100644 src/site/mdtext/setupSteps.mdtext create mode 100644 src/site/mdtext/usersguide.mdtext create mode 100644 src/site/mdtext/usingAdvanced.mdtext create mode 100644 src/site/mdtext/usingEclipse.mdtext create mode 100644 src/site/mdtext/usingGeneral.mdtext create mode 100644 src/site/mdtext/usingIntellij.mdtext create mode 100644 src/site/mdtext/usingNetbeans.mdtext diff --git a/.gitignore b/.gitignore index c6e5efd9..8239b524 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,6 @@ groovy-bin/* .project .classpath .idea -.mdtext atlassian-ide-plugin.xml pom.xml.versionsBackup diff --git a/src/site/mdtext/configentries.mdtext b/src/site/mdtext/configentries.mdtext new file mode 100644 index 00000000..5cf02f7b --- /dev/null +++ b/src/site/mdtext/configentries.mdtext @@ -0,0 +1,112 @@ + +#Navigation Top + [<<Back to the appendix: Setup steps](./setupSteps.html) + or + [On to the appendix: Example Configuration>>](./exampleconfig.html) + +#Appendix: Configuration Entries +## General Information + + This page is a general quick overview over the possible configuration parameters, if you need further + details please visit the[setup guide](./installation.html). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParamRequiredPossible valuesShort Description
org.apache.myfaces.FACES_INIT_PLUGINSYESorg.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoaderMyFaces Extension Point Setup
org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of groovy files on the sources + directory instead of editing in the deployment dir /WEB-INF/groovy +
org.apache.myfaces.extensions.scripting.scala.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of scala files on the sources + directory instead of editing in the deployment dir /WEB-INF/scala + Note this functionality is enabled only in ext-script 1.0.3 or newer +
org.apache.myfaces.extensions.scripting.java.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of java files on the sources + directory instead of editing in the deployment dir /WEB-INF/java +
org.apache.myfaces.extensions.scripting.resource.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of resources on the sources + directory instead of editing in the deployment directory + Important notice, in most cases this path will point to the root of your web application + directory + (ie: src/main/webapp in a standard Maven2 structure or <project-root>/webapp for a + standard + Eclipse project structure) +
facelets.RESOURCE_RESOLVERNOorg.apache.myfaces.extensions.scripting.jsf.facelet.MyFacesReroutingResourceResolverEnables the loading of xhtml facelet pages from your source directory, if + org.apache.myfaces.extensions.scripting.resource.LOADER_PATHS is set properly +
org.apache.myfaces.scripting.PGK_WHITELISTNOa comma separate list of whitelisted packagesEnables package whitelisting, a mechanism which allows to compile and reload only from + whitelisted packages. This can help in case of having to reroute ext-scripting to + your compile source directories. With this option you can isolate your own dynamic classes + from the rest of the system. +
org.apache.myfaces.extensions.scripting.PGK_ADDITIONAL_CLASSPATHNOa comma separate list of additional classpathsenables additional classpaths for the compile time
+ +#Normal configuration entries + all configuration follow the context parameter convention + + + Initializes the plugins for our scripting support + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + +#Navigation Bottom + [<<Back to the appendix: Setup steps](./setupSteps.html) + or + [On to the appendix: Example Configuration>>](./exampleconfig.html) + diff --git a/src/site/mdtext/configentries102.mdtext b/src/site/mdtext/configentries102.mdtext new file mode 100644 index 00000000..8543e191 --- /dev/null +++ b/src/site/mdtext/configentries102.mdtext @@ -0,0 +1,132 @@ + +#Navigation Top + [<<Back to the appendix: Setup steps](./setupSteps.html) + or + [On to the appendix: Example Configuration>>](./exampleconfig102.html) + +#Appendix: Configuration Entries +## General Information + + This page is a general quick overview over the possible configuration parameters, if you need further + details please visit the[setup guide](./installation.html). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParamRequiredPossible valuesShort Description
org.apache.myfaces.FACES_INIT_PLUGINSYESorg.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoaderMyFaces Extension Point Setup
scriptingFilterYES + The scripting filter for further information look below
org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of groovy files on the sources + directory instead of editing in the deployment dir /WEB-INF/groovy +
org.apache.myfaces.extensions.scripting.java.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of java files on the sources + directory instead of editing in the deployment dir /WEB-INF/java +
org.apache.myfaces.extensions.scripting.resource.LOADER_PATHSNOcomma separate list of pathsAdditional comma separated loader paths to allow direct editing of resources on the sources + directory instead of editing in the deployment directory + Important notice, in most cases this path will point to the root of your web application + directory + (ie: src/main/webapp in a standard Maven2 structure or <project-root>/webapp for a + standard + Eclipse project structure) +
facelets.RESOURCE_RESOLVERNOorg.apache.myfaces.extensions.scripting.facelet.ReroutingResourceResolverEnables the loading of xhtml facelet pages from your source directory, if + org.apache.myfaces.extensions.scripting.resource.LOADER_PATHS is set properly +
org.apache.myfaces.scripting.PGK_WHITELISTNOa comma separate list of whitelisted packagesEnables package whitelisting, a mechanism which allows to compile and reload only from + whitelisted packages +
org.apache.myfaces.extensions.scripting.PGK_ADDITIONAL_CLASSPATHNOa comma separate list of additional classpathsenables additional classpaths for the compile time
+ +#Normal configuration entries + all configuration entries except for the scripting filter follow the context parameter convention + + + Initializes the plugins for our scripting support + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + +#Scripting Filter + + All configuration entries are context parameters, the only exception is the scripting filter which is a servlet filter + The scripting filter differs in its configuration by having to provide a servlet filter tag and a pattern: + + + scriptingFilter + org.apache.myfaces.extensions.scripting.servlet.ScriptingServletFilter + + + scriptingFilter + /* + REQUEST + FORWARD + INCLUDE + ERROR + + + + Note for further examples of the configuration go to the section [On to the + appendix: Example Configuration>>](./exampleconfig.html) + +#Navigation Bottom + [<<Back to the appendix: Setup steps](./setupSteps.html) + or + [On to the appendix: Example Configuration>>](./exampleconfig.html) + diff --git a/src/site/mdtext/exampleconfig.mdtext b/src/site/mdtext/exampleconfig.mdtext new file mode 100644 index 00000000..65f90326 --- /dev/null +++ b/src/site/mdtext/exampleconfig.mdtext @@ -0,0 +1,172 @@ + +#Navigation Top + [<<appendix Configuration Entries](./configentries.html) + +#Appendix: Example Configuration +## General Information + + This page gives a detailed example configuration for + Ext-Scripting for installation + details please visit the[setup guide](./installation.html). + + +## Simple Configuration + + MyProject web.xml + + + + Initializes the plugins for our scripting support + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + Faces Servlet + javax.faces.webapp.FacesServlet + 1 + + + + Faces Servlet + *.jsf + + + Faces Servlet + /faces/* + + + + +## Full Configuration + + MyProject web.xml + + + + Initializes the plugins for our groovy handlers + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp/WEB-INF/groovy + + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp/WEB-INF/java + + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp/WEB-INF/scala + + + + + resource paths for our custom JSF2 resource resolver + org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp + + + + + a redirecting Facelet resource resolver which allows to pick up templates and resources from our + source dir + + facelets.RESOURCE_RESOLVER + org.apache.myfaces.extensions.scripting.jsf.facelet.MyFacesReroutingResourceResolver + + + + 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 + + org.apache.myfaces.extensions.scripting.PGK_WHITELIST + org.apache.myfaces.groovyloader.blog,org.apache.myfaces.javaloader.blog + + + + + Additional Classpaths which will be added to the compilers classpath + + org.apache.myfaces.extensions.scripting.PGK_ADDITIONAL_CLASSPATH + /usr/lib/java/myjar.jar,/usr/lib/java/myjar2.jar + + + javax.faces.PROJECT_STAGE + Development + + + + org.apache.webbeans.servlet.WebBeansConfigurationListener + + + + org.apache.myfaces.webapp.StartupServletContextListener + + + + Faces Servlet + javax.faces.webapp.FacesServlet + 1 + + + + Faces Servlet + *.jsf + + + Faces Servlet + /faces/* + + + + + +#Navigation Bottom + [<<appendix Configuration Entries](./configentries.html) + diff --git a/src/site/mdtext/exampleconfig102.mdtext b/src/site/mdtext/exampleconfig102.mdtext new file mode 100644 index 00000000..52d3bb57 --- /dev/null +++ b/src/site/mdtext/exampleconfig102.mdtext @@ -0,0 +1,183 @@ + +#Navigation Top + [<<appendix Configuration Entries](./configentries.html) + +#Appendix: Example Configuration +## General Information + + This page gives a detailed example configuration for + Ext-Scripting for installation + details please visit the[setup guide](./installation.html). + + +## Simple Configuration + + MyProject web.xml + + + + Initializes the plugins for our scripting support + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + scriptingFilter + org.apache.myfaces.extensions.scripting.servlet.ScriptingServletFilter + + + scriptingFilter + /* + REQUEST + FORWARD + INCLUDE + ERROR + + + + Faces Servlet + javax.faces.webapp.FacesServlet + 1 + + + + Faces Servlet + *.jsf + + + Faces Servlet + /faces/* + + + + +## Full Configuration + + MyProject web.xml + + + + Initializes the plugins for our groovy handlers + + org.apache.myfaces.FACES_INIT_PLUGINS + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp/WEB-INF/groovy + + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp/WEB-INF/java + + + + + resource paths for our custom JSF2 resource resolver + org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS + + /Users/werpu2/development/workspace/extensions-scripting3/examples/myfaces20-example/src/main/webapp + + + + + a redirecting Facelet resource resolver which allows to pick up templates and resources from our + source dir + + facelets.RESOURCE_RESOLVER + org.apache.myfaces.extensions.scripting.facelet.ReroutingResourceResolver + + + + 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 + + org.apache.myfaces.extensions.scripting.PGK_WHITELIST + org.apache.myfaces.groovyloader.blog,org.apache.myfaces.javaloader.blog + + + + + Additional Classpaths which will be added to the compilers classpath + + org.apache.myfaces.extensions.scripting.PGK_ADDITIONAL_CLASSPATH + /usr/lib/java/myjar.jar,/usr/lib/java/myjar2.jar + + + javax.faces.PROJECT_STAGE + Development + + + scriptingFilter + org.apache.myfaces.extensions.scripting.servlet.ScriptingServletFilter + + + scriptingFilter + /* + REQUEST + FORWARD + INCLUDE + ERROR + + + + org.apache.myfaces.webapp.StartupServletContextListener + + + + Faces Servlet + javax.faces.webapp.FacesServlet + 1 + + + + Faces Servlet + *.jsf + + + Faces Servlet + /faces/* + + + + + +#Navigation Bottom + [<<appendix Configuration Entries](./configentries.html) + diff --git a/src/site/mdtext/index.mdtext b/src/site/mdtext/index.mdtext new file mode 100644 index 00000000..dd089ac5 --- /dev/null +++ b/src/site/mdtext/index.mdtext @@ -0,0 +1,84 @@ + + + +#Navigation Top + [On to the General Installation Guide>>](./installation.html) + +#Introduction +## General Introduction + Welcome and hello to MyFaces Extension-Scripting, short Ext-Scripting. Ext-Scripting is an extensions + project for MyFaces. It tries to add scripting and rapid prototyping (artifact level hot deployment) + capabilities to JSF by adding + scripting languages and JSP like recompilation mechanisms. + Following link to the a video on YouTube shows you what Ext-Scripting can do for you: + + + + + + + + As the video shows, you can make changes to almost all JSF artifacts on the fly, and at the next + reload the changes are present. + The result is a reduction in server restarts and better turn around times. The + same rapid prototyping approach which is normally present in scripting languages and scripting + language based frameworks. + Additionally to that, Ext-Scripting integrates various scripting languages to be used in conjunction + with JSF, so that a mixed language approach becomes feasible within the bounds of the framework. + + + +#Documentation + + Ext-Scripting provides extensive documentation. Feel free + to browse our + [Installation Guide](./installation.html) + or + [Users Guide](./usersguide.html) + for further information. + + + Also + [download links](./download.html) + are provided on the left hand side of this page, + as well as further information. + + +#Short Overview over Ext-Scripting +## Supported for Scripting Languages + + Ext-Scripting currently only supports Groovy Java and Scala (1.0.3+) as dynamic languages. + Additional languages will be provided in subsequent releases. + + +## Support for JSF2 and JSF2 Artifacts and Annotations + + One of the main goals of Ext-Scripting was to provide JSF2 support out of the box. Most new JSF2 + artifacts are supported. Ext-Scripting even adds scriptability to the new annotation syntax of JSF2 + by allowing annotations to be used in a dynamic manner! + + +## Support for MyFaces + + Extensions scripting supports MyFaces only for now. Following versions are supported. + + + + Older versions are not supported due to missing plugin mechanisms which allow Ext-Scripting to work. + + + The JSF RI and Mojarra as time of writing are not supported due to missing framework hooks needed, + but Mojarra supports Groovy out of the box within the core engine. So for the time being only + MyFaces can be used. Also Portlets for 1.0.x are not supported, this limitation will be eliminated + in future versions. Support for Mojarra maybe will come post 1.0.x. + + + +#Navigation Bottom + [On to the General Installation Guide>>](./installation.html) + + diff --git a/src/site/mdtext/install102.mdtext b/src/site/mdtext/install102.mdtext new file mode 100644 index 00000000..90cc1b16 --- /dev/null +++ b/src/site/mdtext/install102.mdtext @@ -0,0 +1,260 @@ + + + +#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 + + 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 + + + + + + + +#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: + + + + 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. + + + +## 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. + + + +## 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+ + + org.apache.myfaces.extensions.scripting + extscript-myfaces12-bundle + 1.0-SNAPSHOT + + MyFaces 2.+ + + org.apache.myfaces.extensions.scripting + extscript-myfaces20-bundle + 1.0-SNAPSHOT + + + +## 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: + + + 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 + + + Enables our scripting engine support plugins + + org.apache.myfaces.FACES_INIT_PLUGINS + + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + Second Step + Add Ext-Scriptings servlet filter to your servlet configuration + + scriptingFilter + org.apache.myfaces.extensions.scripting.servlet.ScriptingServletFilter + + + scriptingFilter + /*.jsf + REQUEST + FORWARD + INCLUDE + ERROR + + 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: + + /WEB-INF/groovy + + + as root location for Groovy files + + /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! + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + + /src/main/webapp/WEB-INF/groovy + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + + /src/main/webapp/WEB-INF/java + + + +
    +
  • + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + can be a comma separated list of paths which point to the actual Groovy sources. +
    • +
  • + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + does the same for Java sources.. +
    • +
+ + +#Navigation Bottom + [<<Back to the Start Page](./index.html) + or + [On to the General Users Guide>>](./usingGeneral.html) + + diff --git a/src/site/mdtext/installation.mdtext b/src/site/mdtext/installation.mdtext new file mode 100644 index 00000000..40ce782b --- /dev/null +++ b/src/site/mdtext/installation.mdtext @@ -0,0 +1,362 @@ + + + +#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, 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 + + + + + + + +#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: + +
    +
  • A valid Subversion client
    • +
  • A valid Servlet 3.0+ container
    • +
  • Java 6 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 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. + +
    +
  • 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
    • +
  • The paths to the scripts have to be present (see also below)
    • +
+ +## 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+ + + org.apache.myfaces.extensions.scripting + extscript-myfaces20-bundle + 1.0.4 + + Additional language libraries + + You have to add following artifacts to your dependency list for additional language support + + org.codehaus.groovy + groovy-all + 1.7.1 + + + For Groovy support (version number may vary) + + org.scala-lang + scala-library + 2.9.1 + + + org.scala-lang + scala-compiler + 2.9.1 + + + For Scala support. + + For OpenWebbeans support please add following entry: + + org.apache.myfaces.extensions.scripting + extscript-cdi + 1.0.4 + + + + +## 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: +
    +
  • <yourbuilderoot>/extscript-bundles/extscript-myfaces20-bundle/target/extscript-myfaces20-bundle-1.0.3-SNAPSHOT.jar
    • +
+ 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: +
    +
  • commons-beanutils.jar version 1.8.3 or above
    • +
  • commons-codec.jar version 1.3 or above
    • +
  • commons-collections.jar version 3.2 or above
    • +
  • commons-io.jar version 1.4 or above
    • +
  • commons-logging.jar version 1.1.1 or above
    • +
  • commons-digester version 1.8 or above
    • +
  • groovy-all.jar version 1.7.2 or above
    • +
  • scala-compiler.jar version 2.10.0-M2 or above
    • +
  • scala-library.jar version 2.10.0-M2 or above
    • +
+ 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 + + + Enables our scripting engine support plugins + + org.apache.myfaces.FACES_INIT_PLUGINS + + org.apache.myfaces.extensions.scripting.servlet.StartupServletContextPluginChainLoader + + + 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: + + /WEB-INF/groovy + + + as root location for Groovy files + + /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! + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + + /src/main/webapp/WEB-INF/groovy + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + + /src/main/webapp/WEB-INF/java + + + + Additional comma separated loader paths to allow direct editing on the sources directory instead + of the deployment dir + + org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS + + /src/main/webapp/WEB-INF/scala + + + +
    +
  • + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + can be a comma separated list of paths which point to the actual Groovy sources. +
    • +
  • + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + does the same for Java sources.. +
    • +
  • + org.apache.myfaces.extensions.scripting.scala.LOADER_PATHS + does the same for Java Scala (Ext-Scripting 1.0.3 or newer)... +
    • +
+ 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. + + +
    +
  • + org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS + This parameter points to the root of your dynamic resources, usually the same dir + as the root of your web application. +
    • +
  • facelets.RESOURCE_RESOLVER also needs to be set to org.apache.myfaces.extensions.scripting.jsf.facelet.MyFacesReroutingResourceResolver if + you want dynamic Facelet reloading enabled
    • +
+ + + resource paths for our custom JSF2 resource resolver + org.apache.myfaces.extensions.scripting.resources.LOADER_PATHS + + ~/extensions-scripting3/examples/myfaces20-example/src/main/webapp + + + + + a redirecting Facelet resource resolver which allows to pick up templates + and resources from our source dir + + facelets.RESOURCE_RESOLVER + org.apache.myfaces.extensions.scripting.jsf.facelet.MyFacesReroutingResourceResolver + + + + 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: + + + 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 + + org.apache.myfaces.extensions.scripting.PGK_WHITELIST + org.apache.myfaces.groovyloader.blog,org.apache.myfaces.javaloader.blog + + + +## 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: + + + org.apache.webbeans.servlet.WebBeansConfigurationListener + + + + + +#Navigation Bottom + [<<Back to the Start Page](./index.html) + or + [On to the General Users Guide>>](./usingGeneral.html) + + diff --git a/src/site/mdtext/issuetracking.mdtext b/src/site/mdtext/issuetracking.mdtext new file mode 100644 index 00000000..3728931f --- /dev/null +++ b/src/site/mdtext/issuetracking.mdtext @@ -0,0 +1,6 @@ + +#Issue Tracking + This project uses JIRA a J2EE-based, issue tracking and project management application. + Issues, bugs, and feature requests should be submitted to the following issue tracking system for this project. + [Apache JIRA For MyFaces Extension Scripting](https://issues.apache.org/jira/browse/EXTSCRIPT) + diff --git a/src/site/mdtext/setupSteps.mdtext b/src/site/mdtext/setupSteps.mdtext new file mode 100644 index 00000000..8e5e3243 --- /dev/null +++ b/src/site/mdtext/setupSteps.mdtext @@ -0,0 +1,56 @@ + + + +#Navigation Top + [<<Back to the Netbeans Users Guide](./usingNetbeans.html) + or + [On to the configuration entries overview>>](./configentries.html) + +#Appendix: Setup Steps +## Short setup overview + This section is only a checklist of things to do at the setup for details follow the explanations + in the [page](./installation.html) + + + Manual setup +
    +
  • Check if your installation environment is setup
    • +
  • Download the appropriate meta bundle and place it in WEB-INF/lib
    • +
  • Download groovy-all.jar and or (scala-lang.jar and scala-compiler.jar) and place it in + WEB-INF/lib
    • +
  • Prepare your script paths (WEB-INF/java, WEB-INF/groovy, WEB-INF/scala)
    • +
  • Add your web.xml entries
    • +
  • start the web application ...
    • +
+ + + Build via maven +
    +
  • Check if your installation environment is setup
    • +
  • Add your pom xml dependencies and the repository entry
    • +
  • Prepare your script paths (WEB-INF/java, WEB-INF/groovy, WEB-INF/scala)
    • +
  • Add your web.xml entries
    • +
  • mvn clean install ...
    • +
+ + + Build via ide +
    +
  • Check if your installation environment is setup
    • +
  • Download the appropriate meta bundle and add it to your dependency and deployment settings + (for the download location check the download page) +
    • +
  • Download groovy-all.jar and add it to your dependency and deployment settings
    • +
  • Prepare your script paths
    • +
  • Add your web.xml entries
    • +
  • start the web application ...
    • +
+ + + +#Navigation Bottom + [<<Back to the Netbeans Users Guide](./usingNetbeans.html) + or + [On to the configuration entries overview>>](./configentries.html) + + diff --git a/src/site/mdtext/usersguide.mdtext b/src/site/mdtext/usersguide.mdtext new file mode 100644 index 00000000..5114dd54 --- /dev/null +++ b/src/site/mdtext/usersguide.mdtext @@ -0,0 +1,77 @@ + + + +#Navigation Top + [<<Back to the Setup Guide](./installation.html) or + [On to the General Users Guide>>](./usingGeneral.html) + +#Users Guide + + After having set up MyFaces Ext-Scripting (if you do not have done so please go to our[Installation Page](./installation.html)), you basically can start editing, and be done with + the users + guide. + + + Well theoretically anyway, there are some things every user of Extension-Scripting has to take into + consideration. + + + First of all Ext-Scripting in its current incarnation tries to help the programmers every day life. That + means, it tries to reduce the number of needed server restarts to the lowest possible minimum which is + achievable within the boundaries of Java and JSF. + Also it is not yet fully integrated into the bigger application servers, testing only currently is + done for Apache Tomcat and Jetty. Scala due to the nature of its compiler interface, definitely only + will work in an expanded embedded WAR environment, not in an EAR environment. + + + You won't get a zero restart configuration, Extension-Scripting tries not to be perfect in this regard, + but + what you can achieve is a significant reduction on restarts by applying scripting languages and dynamic + compilation. + + + Secondly, we do not try to support every scripting language under the earth, the basic goal is first to + get + the basics right and then in subsequent releases to add additional scripting languages support. + + + As is, every scripting language which can compile against the JVM can be supported. Purely interpreted + languages are not supported. + + + For now we cannot recommend to use Ext-Scripting in a production environment for live patches, although + it + theoretically would be possible, and we spent a lot of blood sweat and tears into making the system + stable + under multithreaded conditions. For now, however, we simply only can recommend to use Ext-Scripting for + development and development only scenarios if you need to hot patch code (deployment without any changes + however should be fine). So if you want to hot patch a running installations, we assume it should work + fine, + but you are on your own. + + +#Chapters + The Following Chapters should help you to guide you through the usage of Ext-Scripting + + +#Navigation Bottom + [<<Back to the Setup Guide](./installation.html) or + [On to the General Users Guide>>](./usingGeneral.html) + + diff --git a/src/site/mdtext/usingAdvanced.mdtext b/src/site/mdtext/usingAdvanced.mdtext new file mode 100644 index 00000000..614b34e4 --- /dev/null +++ b/src/site/mdtext/usingAdvanced.mdtext @@ -0,0 +1,437 @@ + + + +#Navigation Top + [<<Back to the General Users Guide](./usingGeneral.html) + or + [On to the Eclipse Users Guide>>](./usingEclipse.html) + +#Introduction + Congratulations by the time you have reached this section, you probably have mastered the basics + of Ext-Scripting, you probably already can edit your local files and have them refreshed on the fly + + + Under normal circumstances you, should be set up by now and you can start coding happily. + However since this is a framework based reloading mechanism it is wise to dig a little bit deeper + and to know what is happening under the hood and why things behave like they do. + If you are interested then read on. + + +#Helper Components +## Overview + Additionally to the standard reloading feature, Ext-Scripting provides two components + which hopefully will make the life of every programmer easier. + + +
    +
  • The Compiler Output Component
    • +
  • The Change History Component
    • +
+ + Note currently and for the foreseeable future only Facelets as page description language + will be supported by the components. + + +## Setup + To use the components following namespace has to be included + + xmlns:exs="http://myfaces.apache.org/ext-scripting" + + Example + + + + + + +## The Compiler Output Component + One of the cornerstones of Ext-Scripting is the dynamic recompilation. + Every file changed, is reloaded, while you hit refresh on the browser. + + + Now, under normal circumstances, the compiler errors and warnings are written to the console log + as following: + Java Compiler, Error on line: + org/apache/myfaces/javaloader/blog/Blog.java:30: + class, interface, or enum expected30 + + + Now, trying to catch those errors within the log is "mildly spoken" annoying + and time consuming. + Exactly for bypassing this problem a compiler output component + can be used either in your page or preferably in a second page. + + The following Video shows the compiler output component in action + + + + + Video: Compiler Component in Action + + + Usage of the Compiler Output Component + + The compiler output component currently is presented as Facelets only component as follows + + Following attributes can be used + + + + + + + + + + + + + + + + + + + + + + + + +
Attribute NamePossible ValuesDescription
errorsLabelAll values are allowedA Label which is displayed in above all errors to notify the user that the error section + starts here +
WarningsLabelAll values are allowedA Label which is displayed in above all errors to notify the user that the warning + section + starts here +
scriptingLanguageJava, Groovy or an empty StringScripting language filter, here you can set which scripting engines + compile errors should be displayed, currently Java or Groovy are supported as values + if you leave the attribute empty or set nothing then everything is displayed +
+ + ![Image Compiler Output](images/compiler-output.png) + Image: Compiler Output Component + +## The Change History Component + The second cornerstone of Ext-Scripting is change tracking and dependency detection. + Now if you have changed a file, Ext-Scripting tracks the changes and also marks + most classes which have a dependency to your class as changed. + + + Again usually the output is pushed into the log as following: + + + INFO: [EXT-SCRIPTING] Tainting: org/apache/myfaces/javaloader/componentTest/MyComponentTag.java + + + Again, to get a quick overview within your running page, or preferably an extra page, you can use + a specialized component which gives you a quick overview over the change history of the system. + + + Here our change history component comes into play. With it you can track a certain number of changes + done over time including their marked dependencies. + + + + ![change history component](images/change-history.jpg) + Image: Change History Component in Action + + + + + Usage + + The change history component can be currently used in Facelets only as follows + + Following attributes can be used + + + + + + + + + + + + + + +
Attribute NamePossible ValuesDescription
noEntriesThe <Integer Value> number of entries of the current historyA positive Integer value which shows the last N entries of your history + beginning with the latest change marker on top +
+ + +#Debugging + Ext-Scripting automatically compiles with the debug flags on. Debugging against a running configuration + should be no problem. If the debugger can be pointed towards the sources, debugging should work without + any side effects. + + + Due to the fact that the debugger can pick up the debug info from the newly compiled class + files. (Note - the class files are not altered in any way so in any case you just deal with normal Java + classes) + + TODO add video here + +#Page and Resource Reloading +## Introduction + One of the goals of Ext-Scripting is to prevent unnecessary restarts and redeploys during + development. To + enable this, it provides custom functionality outside of the scope of providing scripting + capabilities. + One of those features is the page and resource reloading from your source directories. + + +## Basic Functionality + Pages and web-resources like CSS files or images are loaded from your resource directory without + having to redeploy the web + application, + changes on them can be watched on the fly simple by a browser reload. There is no need to adjust + your web application server or your IDE for auto deployment mechanisms. Unnecessary web application + restarts for changed resources can be avoided that way. + Note while page reloading works on the fly for both JSF 1.2 and JSF 2.x+, resource reloading + only works for JSF2.x+, if you need similar functionality for JSF 1.x you can use + a third party resource loading library like [Weblets](weblets.dev.java.net). + + + ![Page and Resource Reloading](images/source-resource.jpg) + + +## Setup and Usage + The central point of setting up your resource reloading are two configuration parameters +
    +
  • org.apache.myfaces.extensions.scripting.resource.LOADER_PATHS
    • +
  • facelets.RESOURCE_RESOLVER
    • +
+ + The first parameter org.apache.myfaces.extensions.scripting.resource.LOADER_PATHS defines + the root path for your resources (aka everything web related, like xhtml facelet templates css files etc..). + Note, despite being called resource LOADER_PATH in most cases this path will just be pointed + to the your source web application root directory. + (ie: src/main/webapp in a standard Maven2 structure or <project-root>/webapp for a standard + Eclipse project structure. + The name resource just refers to the fact that for Ext-Scripting every web related file is seen as resource + + + The second parameter facelets.RESOURCE_RESOLVER is responsible for enabling the resouce loading + of Facelet templates and pages, since Facelets does not have an auto plugging mechanism this has + to be + set to a standard value which is org.apache.myfaces.extensions.scripting.jsf.facelet.MyFacesReroutingResourceResolver + + + For further reference please also visit out [Appendix: Configuration Entries Overview](./configentries.html) + page. + + + +#Advanced Dependency Detection + + Ext-Scripting tries to avoid as many server restarts as possible. To enable this it needs to unload + recompile and load artifacts and the those which reference our changed ones. To enable this, + Ext-Scripting + does dependency detection on bytecode level as well as on artifact level. This functionality is enabled + automatically you wont have anything further to do. You can see it working by watching the output log, + if + you change a class, you automatically will see that the system marks the classes which reference your + changed class as tainted as well. + + + You have to have in mind that data currently in ram cannot be recovered by the unloading and reloading + happening, so everything stored for instance in application or session scope is lost that way. + + + Following video shows the mechanism working: + + + + + + + + + This dependency detection works over all dynamic classes, no matter being it classes, interfaces, + annotations, and it works over static and dynamic imports. + + + Javabean dependencies also are detected on artifact level so that if the JSF IOC mechanism is used those + bound over neutral Object classes also will reload the dependencies correctly. + + +#Dynamic Annotations + One of the main features which Ext-Scripting provides over standard JSF is dynamic annotations. + Dynamic annotations basically introduces a mechanism so that your standard JSF annotations like + @ManagedBean or @FacesComponent or @ManagedProperty or even the scopes like @RequestScoped or + @SessionScoped + can be changed on the fly in a dynamic way. + + To enable this mechanism you don't have to do anything, it comes out of the box in a MyFaces 2.0 + environment. + Following video demonstrates the mechanism + + + + + + + +#Supported Artifacts +## JSF 1.2 + Ext-Scripting supports following JSF 1.2 artifact reloading: +
    +
  • ApplicationFactory reloading on method call level
    • +
  • FacesContextFactory reloading on method call level
    • +
  • LifecycleFactory reloading on method call level
    • +
  • RenderkitFactory reloading on method call level
    • +
  • ElResolver
    • +
  • Converter (on JSF level alone)
    • +
  • Validator (on JSF level alone)
    • +
  • Component reloading on component tree creation level (on JSF level alone)
    • +
  • ViewHandler
    • +
  • Lifecycle
    • +
  • Renderer
    • +
  • PhaseListener
    • +
  • ManagedBeans reloading for all managed beans even session and application scoped ones on request + level +
    • +
  • Support for either JavaC or JSR 199 depending on your JDK Version
    • +
  • Support for Groovy and Java
    • +
+ +## JSF 2.0 + Ext-Scripting supports following JSF 2.0 artifact reloading: Additionally to what is present for JSF + 1.2 + +
    +
  • Component limitations have been lifted for Facelets as rendering language
    • +
  • All major JSF 2 annotations can be used in a dynamic way, annotations can be moved removed or + added on the fly +
    • +
  • Support for Reloading on ComponentTagHandler, ConverterTagHandler, BehaviorTagHandler, + ValidatorTagHandler +
    • +
  • ResourceHandler
    • +
  • Behavior
    • +
  • BehaviorRenderer
    • +
  • ComponentSystemEvent Support via dynamic Annotations
    • +
  • Application System Event Support
    • +
+ +## Visual Overview + ![](images/ext-scripting-structure-fine.jpg) + + +#Extension Frameworks +## EXT-SCRIPTING and EXT-VAL + While the target of supporting extension frameworks will be post 1.0 Ext-Scripting already + supports dynamic bean validation and Ext-Val + + To setup Ext-Val simply add the needed dependencies and you can start to use it instantly + The MyFaces 2.0 demo has a simple example ported over from the Ext-Val distribution which + shows the dynamic aspects of using Ext-Val and Ext-Scripting combined + + The same what applies to Ext-Val also applies to straight bean validation. + Note at the time of release, the current stable version of Ext-Val has a bug + which enforces one manual configuration entry! + + + + org.apache.myfaces.extensions.scripting.startup.SuppressExtValWarningStartupListener + javax.faces.event.PostConstructApplicationEvent + + + + Note the class already is provided by Ext-Scripting, all which has done is + to add this entry to bypass the error. + This class probably will be obsolete with Ext-Val versions higher than + 2.0.3 (which was the latest stable at time of writing) + +## EXT-SCRIPTING and Spring + Currently there is no direct Spring support for Ext-Scripting, it however is in the works + and will be delivered in a release post 1.0 + + +## EXT-SCRIPTING and CDI + Currently there is no direct CDI support for Ext-Scripting, it however the + work on it will be started post 1.0 + + + + +#Build Process and Multiuser Environments + While Ext-Scripting itself is only used for rapid prototyping following two szenarii will probably occur in a typical + user development environment +## Compiling the Groovy classes for the final build + while it makes sense to have the Groovy sources for editing, for the final deployment, it makes sense + to just deliver the classes instead of the source files. + While doing that for your ide is out of scope of this documentation (currently). The documentation can provide you the information on how + to do it in Apache Maven: + The trick is to combine two things. Apache Maven 2 profiles and the Apache Maven2 groovy plugin + For a short explanation on Apache Maven 2 profiles please follow this link: [Apache Maven 2 Profiles](http://maven.apache.org/guides/introduction/introduction-to-profiles.html) + The idea is, to define a deployment profile which triggers the Maven 2 groovy plugin which then will compile your classes, here is an example + configuration of such a profile, which can be copy pasted into your build file + + + + deployment + + + org.codehaus.gmaven + gmaven-plugin + 1.2 + + 1.7 + + + + + generateStubs + compile + generateTestStubs + testCompile + + + + + + org.codehaus.groovy + groovy-all + 1.7.1 + + + + + + + + + The standard settings of the groovy maven plugin is that it will use your src/main/groovy directory as the path to pickup the sources. + You either can use that one and adjust the corresponding org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS setting for editing. + Or you can readjust the corresponding plugin settings of the Groovy Maven plugin. Follow this [link](http://groovy.codehaus.org/GMaven) for further information. + + A call to maven clean install -P deployment now triggers the groovy compile task. You also can use the extended features + of the maven profiles to automate the switch if you use maven also for deployment of your project. + +## Multi Developer Scenario's + One problem you might have noticed is, that if you do not work with the default configuration on your sources + (aka. WEB-INF/<scripting-language>, you have to rely on the corresponding configuration entries, which in itself take absolute paths. + One user of the system came up with the question, on how to deal with multiple developers. The answer is plain and simple, unfortunately the + support of such a use case could be better for 1.0, all you can do is either to rely on the default paths, or use your build system to handle + the configuration parts per user, or standardize on the same file structure for every user. + Additional support for this scenario will be added post 1.0 to ease this usecase but for now it is a known but not entirely solved problem. + + + +#Navigation Bottom + [<<Back to the General Users Guide](./usingGeneral.html) + or + [On to the Eclipse Users Guide>>](./usingEclipse.html) + + diff --git a/src/site/mdtext/usingEclipse.mdtext b/src/site/mdtext/usingEclipse.mdtext new file mode 100644 index 00000000..332cdf59 --- /dev/null +++ b/src/site/mdtext/usingEclipse.mdtext @@ -0,0 +1,56 @@ + + + +#Navigation Top + [<<Back to the Advanced Users Guide](./usingAdvanced.html) + or + [On to the Intellij Users Guide>>](./usingIntellij.html) + +#Introduction + + Eclipse is somewhat different to the rest of the IDEs because it allows to compile classes on the fly. + But yet still Ext-Scripting and Eclipse are a good combination, but several things have to be taken into + consideration. + +
    +
  • Ext-Scripting does its own incremental compile cycle depending on the sources changed
    • +
  • Deployment and Redeployment is not needed as long as Ext-Scripting itself can pick up the changes +
    • +
+ +#Setting up Eclipse +## Prerequirements + Secondly make sure that your project compiles properly + and can be properly deployed from eclipse. Turn off any auto deployment mechanisms + which might trigger unnecessary restarts. + + If you use scripting languages make sure to have the proper + plugin installed for the scripting language of your choice + + + +#Setting up Ext-Scripting specifics + + If you only have one sourcepath you might have a look at the package whitelisting + to mark only the packages you actively want to edit for this deployment cycle. + This speeds up startup time and helps generally to avoid restarts. + + + If you use different paths then you can work by including the added source paths as sources + like WEB-INF/java or WEB-INF/groovy (not classes compiled via Ext-Scripting always have higher loading + priority than what can be found in WEB-INF/classes), so there is no need to change any target directories + source directories always are enough. + + + You can leave your compile target directory unchanged + + + If you prefer your own source paths to be the sources of everything set the + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + or + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + accordingly in your web.xml the same goes for the resource roots. + + + TODO add images here + diff --git a/src/site/mdtext/usingGeneral.mdtext b/src/site/mdtext/usingGeneral.mdtext new file mode 100644 index 00000000..0db057f8 --- /dev/null +++ b/src/site/mdtext/usingGeneral.mdtext @@ -0,0 +1,40 @@ + + + +#Navigation Top + [<<Back to the Users Guide Start](./usersguide.html) + or + [On to the Advanced Users Guide>>](./usingAdvanced.html) + +#General Users Guide + + Using Ext-Scripting once properly setup is straight forward. Usually it comes down to editing, reloading + on + the browser editing, reloading the page, .... However if you edit within a running configurations keep + an + eye on the console/log output. All compile errors and messages go automatically into the log. + + + ![](images/development-states.jpg) + + Image: Development Lifecycle + + The development cycle also can seen in the following video + and in the following videos in the Users Guide. + + + + + Video: Development Lifecycle in Action + + As you can see, there is no need for any recompile anymore, no server restart + everything is done dynamically, and you get instant results. + + +#Navigation Bottom + [<<Back to the Users Guide Start](./usersguide.html) + or + [On to the Advanced Users Guide>>](./usingAdvanced.html) + + diff --git a/src/site/mdtext/usingIntellij.mdtext b/src/site/mdtext/usingIntellij.mdtext new file mode 100644 index 00000000..ccba7e8c --- /dev/null +++ b/src/site/mdtext/usingIntellij.mdtext @@ -0,0 +1,65 @@ + + + +#Navigation Top + [<<Back to the Eclipse Users Guide](./usingEclipse.html) + or + [On to the NetBeans Users Guide>>](./usingNetbeans.html) + +#Introduction + + Intellij is very specific because it allows mixed programming out of the box, hence it is the ideal + partner for mixing it with Ext-Scripting. However while setting everything up you have to be aware + of several specifics. + +
    +
  • Ext-Scripting does its own incremental compile cycle depending on the sources changed
    • +
  • Deployment and Redeployment is not needed as long as Ext-Scripting itself can pick up the changes +
    • +
+ +#Setting up Eclipse +## Prerequirements + Secondly make sure that your project compiles properly + and can be properly deployed from Idea. Turn off any auto deployment mechanisms + which might trigger unnecessary restarts. + + If you use scripting languages make sure to have the proper + plugin installed for the scripting language of your choice + + + +#Setting up Ext-Scripting specifics + + If you only have one sourcepath you might have a look at the package whitelisting + to mark only the packages you actively want to edit for this deployment cycle. + This speeds up startup time and helps generally to avoid restarts. + + + If you use different paths then you can work by including the added source paths as sources + like WEB-INF/java or WEB-INF/groovy (not classes compiled via Ext-Scripting always have higher loading + priority than what can be found in WEB-INF/classes), so there is no need to change any target + directories + source directories always are enough. + To change your source directories open + File->Project Structure ->Modules-><Your Web Module> + and mark your script directories as source paths: + ![setting the sourcepath from Intellij](images/intellij-source.jpg) + + + You can leave your compile target directory unchanged + + + If you prefer your own source paths to be the sources of everything set the + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + or + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + accordingly in your web.xml the same goes for the resource roots. + + +#Navigation Bottom + [<<Back to the Eclipse Users Guide](./usingEclipse.html) + or + [On to the NetBeans Users Guide>>](./usingNetbeans.html) + + diff --git a/src/site/mdtext/usingNetbeans.mdtext b/src/site/mdtext/usingNetbeans.mdtext new file mode 100644 index 00000000..1f8ffeb9 --- /dev/null +++ b/src/site/mdtext/usingNetbeans.mdtext @@ -0,0 +1,72 @@ + + + +#Navigation Top + [<<Back to the Intellij Users Guide](./usingIntellij.html) + or + [On to the appendix: Setup Steps>>](./setupSteps.html) + +#Introduction + + Netbeans also works perfectly in conjunction with Ext-Scripting + pretty much everything said for Eclipse and Intellij also applies to NetBeans. + The biggest restriction is if you want to use Netbeans in conjunction with maven + only one source folder is picked up and you cannot use additional source folders + like for instance Intellij or Eclipse allow. So either dont use maven or + use package whitelisting as workaround if you want to use Netbeans. + +
    +
  • Ext-Scripting does its own incremental compile cycle depending on the sources changed
    • +
  • Deployment and Redeployment is not needed as long as Ext-Scripting itself can pick up the changes +
    • +
+ +#Setting up Eclipse +## Prerequirements + Secondly make sure that your project compiles properly + and can be properly deployed from Netbeans. Turn off any auto deployment mechanisms + which might trigger unnecessary restarts. + + If you use scripting languages make sure to have the proper + plugin installed for the scripting language of your choice + + + +#Setting up Ext-Scripting specifics + + If you only have one source path you might have a look at the package whitelisting + to mark only the packages you actively want to edit for this deployment cycle. + This speeds up startup time and helps generally to avoid restarts. + + + If you use different paths then you can work by including the added source paths as sources + like WEB-INF/java or WEB-INF/groovy (not classes compiled via Ext-Scripting always have higher loading + priority than what can be found in WEB-INF/classes), so there is no need to change any target + directories + source directories always are enough. + To change your source directories open + File->Project Properties -> Sources - > Source Package Folders + and press the Add Folder button + + ![setting the sourcepath from Intellij](images/netbeans-source1.jpg) + + After that you get a file dialog where you can choose your source directory. + + ![setting the sourcepath from Intellij](images/netbeans-source2.jpg) + + You can leave your compile target directory unchanged + + + If you prefer your own source paths to be the sources of everything set the + org.apache.myfaces.extensions.scripting.java.LOADER_PATHS + or + org.apache.myfaces.extensions.scripting.groovy.LOADER_PATHS + accordingly in your web.xml the same goes for the resource roots. + + +#Navigation Bottom + [<<Back to the Intellij Users Guide](./usingIntellij.html) + or + [On to the appendix: Setup Steps>>](./setupSteps.html) + +