<!--
    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 General Users Guide](./usingGeneral.html)
 or
 [On to the Eclipse Users Guide&gt;&gt;](./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.
 
 
<ul>
   <li>The Compiler Output Component</li>
   <li>The Change History Component</li>
</ul>
 
 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
 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
            "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:exs="http://myfaces.apache.org/ext-scripting"
          xmlns:h="http://java.sun.com/jsf/html">
    <h:head>
 
 
## 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
 
 
 <iframe class="youtube-player" type="text/html" width="640" height="505" src="http://www.youtube.com/embed/v56ru9ZJyhQ" frameborder="0">
 </iframe>
 
 Video: Compiler Component in Action
 
 
 Usage of the Compiler Output Component
 
 The compiler output component currently is presented as Facelets only component as follows
                        <exs:compilerOutput errorsLabel="Errors:" warningsLabel="Warnings:" scriptingLanguage=""/>
 Following attributes can be used
 
<table>
   <thead>
       <tr>
           <td>Attribute Name</td>
           <td>Possible Values</td>
           <td>Description</td>
       </tr>
   </thead>
   <tr>
       <td>errorsLabel</td>
       <td>All values are allowed</td>
       <td>A Label which is displayed in above all errors to notify the user that the error section
           starts here
       </td>
   </tr>
   <tr>
       <td>WarningsLabel</td>
       <td>All values are allowed</td>
       <td>A Label which is displayed in above all errors to notify the user that the warning
           section
           starts here
       </td>
   </tr>
   <tr>
       <td>scriptingLanguage</td>
       <td>Java, Groovy or an empty String</td>
       <td>Scripting 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
       </td>
   </tr>
</table>
 
 ![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
    <exs:taintHistory noEntries="5" />
 Following attributes can be used
 
<table>
   <thead>
       <tr>
           <td>Attribute Name</td>
           <td>Possible Values</td>
           <td>Description</td>
       </tr>
   </thead>
   <tr>
       <td>noEntries</td>
       <td>The &lt;Integer Value&gt; number of entries of the current history</td>
       <td>A positive Integer value which shows the last N entries of your history
           beginning with the latest change marker on top
       </td>
   </tr>
</table>
 
 
#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
<ul>
   <li>org.apache.myfaces.extensions.scripting.resource.LOADER_PATHS</li>
   <li>facelets.RESOURCE_RESOLVER</li>
</ul>
 
 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 &lt;project-root&gt;/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:
 
 
 
 
 <iframe class="youtube-player" type="text/html" width="660" height="405" src="http://www.youtube.com/embed/YWlBGE3vyMw" frameborder="0">
 </iframe>
 
 
 
 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
 
 
 
 <iframe class="youtube-player" type="text/html" width="640" height="505" src="http://www.youtube.com/embed/tikOR0XDnFw" frameborder="0">
 </iframe>
 
 
 
#Supported Artifacts
## JSF 1.2
 Ext-Scripting supports following JSF 1.2 artifact reloading:
<ul>
   <li>ApplicationFactory reloading on method call level</li>
   <li>FacesContextFactory reloading on method call level</li>
   <li>LifecycleFactory reloading on method call level</li>
   <li>RenderkitFactory reloading on method call level</li>
   <li>ElResolver</li>
   <li>Converter (on JSF level alone)</li>
   <li>Validator (on JSF level alone)</li>
   <li>Component reloading on component tree creation level (on JSF level alone)</li>
   <li>ViewHandler</li>
   <li>Lifecycle</li>
   <li>Renderer</li>
   <li>PhaseListener</li>
   <li>ManagedBeans reloading for all managed beans even session and application scoped ones on request
       level
   </li>
   <li>Support for either JavaC or JSR 199 depending on your JDK Version</li>
   <li>Support for Groovy and Java</li>
</ul>
 
## JSF 2.0
 Ext-Scripting supports following JSF 2.0 artifact reloading: Additionally to what is present for JSF
 1.2
 
<ul>
   <li>Component limitations have been lifted for Facelets as rendering language</li>
   <li>All major JSF 2 annotations can be used in a dynamic way, annotations can be moved removed or
       added on the fly
   </li>
   <li>Support for Reloading on ComponentTagHandler, ConverterTagHandler, BehaviorTagHandler,
       ValidatorTagHandler
   </li>
   <li>ResourceHandler</li>
   <li>Behavior</li>
   <li>BehaviorRenderer</li>
   <li>ComponentSystemEvent Support via dynamic Annotations</li>
   <li>Application System Event Support</li>
</ul>
 
## 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!
                    <application>
                        <!-- disable an Ext-Val warning which is triggered falsely by the latest version -->
                        <system-event-listener>
                            <system-event-listener-class>org.apache.myfaces.extensions.scripting.startup.SuppressExtValWarningStartupListener</system-event-listener-class>
                            <system-event-class>javax.faces.event.PostConstructApplicationEvent</system-event-class>
                        </system-event-listener>
                    </application>
                    
 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
 
                         <profiles>
                             <profile>
                                 <id>deployment</id>
                                 <plugins>
                                     <plugin>
                                        <groupId>org.codehaus.gmaven</groupId>
                                        <artifactId>gmaven-plugin</artifactId>
                                        <version>1.2</version>
                                        <configuration>
                                            <providerSelection>1.7</providerSelection>
                                        </configuration>
                                        <executions>
                                            <execution>
                                                <goals>
                                                    <goal>generateStubs</goal>
                                                    <goal>compile</goal>
                                                    <goal>generateTestStubs</goal>
                                                    <goal>testCompile</goal>
                                                </goals>
                                            </execution>
                                        </executions>
                                        <dependencies>
                                            <dependency>
                                                <groupId>org.codehaus.groovy</groupId>
                                                <artifactId>groovy-all</artifactId>
                                                <version>1.7.1</version>
                                            </dependency>
                                        </dependencies>
                                    </plugin>
                                </profile>
                            </plugins>
                        </profiles>
                    
 
 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/&lt;scripting-language&gt;, 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
 [&lt;&lt;Back to the General Users Guide](./usingGeneral.html)
 or
 [On to the Eclipse Users Guide&gt;&gt;](./usingEclipse.html)