Macromedia flex is all about building RIA (Rich Internet Applications), using the standard web development tools. It provides the ability to create RIA interfaces extremely quickly producing compelling applications. With this in mind, it's a perfect fit for Workshops approach to backend server side development, and thus the two products complement each other well.

This article shows you how to add Flex capabilities to your BEA Workshop Application.

Expanding the Web Archive

The main engine of Flex is shipped in the flex.war file contained in the installation directory. In order to get at the requried files, you'll need to expand this directory:

1. Create a new directory under the installation directory called Flex: md Flex
2. Change directory to flex: cd Flex
3. Expand the Web Archive : jar -xf ..\flex.war

Create the new Workshop Application

Now we need to create a new application to which to add Flex:

1. Start Workshop
2. Choose the File -> New Application menu
3. Choose Default Application and set the directory and project name
4. Click create and Workshop will show you your new application with one web app called <applicationName>Web

Adding the flex directory

The 'Flex engine' is contained the the WEB-INF/flex directory of the flex.war file we expanded earlier. This needs to be added to our Workshop web application

1. Expand the Web project
2. Right click on the WEB-INF folder and choose Import from the menu.
3. In the Import dialog, find the Flex/WEB-INF in the directory of the exploded flex.war we created earlier
4. Click on the flex directory
5. Click Import and the flex directory will be imported into the WEB-INF directory of your web app. You can test this by expanding the WEB-INF directory in the project.

Adding the bootstrap jar

Although we've added all the main 'Flex engine' libraries to our application, there is still one more called flex-bootstrap.jar which contains all the Servlets etc which plug Flex into the WebApp container:

1. If you haven't done so already, expand the WEB-INF directory in your web project
2. Right click on lib and then choose import from the menu
3. In the Import dialog, find the Flex/WEB-INF/lib directory in the directory of the exploded flex.war we created earlier
4. Click flex-bootstrap.jar
5. Click Import and the file will be added to the WEB-INF/lib directory of your web app. You can check this by expanding the lib directory.

Updating the WebApp descriptor

Now that all the libraries have been added to our Workshop application, we need to update the WebApp container descriptor to tell it about the Flex servlets. This is done by editing the WEB-INF/web.xml file and adding the Flex configuration details. [If you don't want to do this by hand, I've included a pre-built Workshop WebApp + Flex in the file section. Please bear in mind that this web.xml will ONLY work for a WebApp and not for projects such as Portal]

1. Double click on the WEB-INF/web.xml file in your WebApp project
2. Add the following just under the <display-name>Workshop Application</display-name> tag:

<!-- START Flex WebApp Context Config -->
    <context-param>
       <param-name>flex.class.path</param-name>
       <param-value>./WEB-INF/flex/jars</param-value>
    </context-param>

    <context-param>
      <param-name>flex.configuration.file</param-name>
      <param-value>/WEB-INF/flex/flex-config.xml</param-value>
      <description>configuration file</description>
    </context-param>

    <context-param>
        <param-name>flex.listener.class</param-name>
        <param-value>flex.cache.DependencyCheckerService</param-value>
    </context-param>
<!--  END Flex WebApp Context Config -->

<!-- START Flex Filters -->
    <filter>
      <filter-name>FlexDetectionFilter</filter-name>
      <filter-class>flex.bootstrap.BootstrapFilter</filter-class>
      <init-param>
        <param-name>filter.class</param-name>
        <param-value>flex.detection.DetectionFilter</param-value>
      </init-param>
    </filter>

    <filter>
      <filter-name>FlexCacheFilter</filter-name>
      <filter-class>flex.bootstrap.BootstrapFilter</filter-class>
      <init-param>
          <param-name>filter.class</param-name>
          <param-value>flex.cache.CacheFilter</param-value>
      </init-param>
    </filter>
<!-- END Flex Filters -->    

Add the following directly under the </filter> of the PageFlowJSPFilter:

<!-- Start Flex Filter Mapping -->
    <filter-mapping>
      <filter-name>FlexDetectionFilter</filter-name>
      <servlet-name>FlexMxmlServlet</servlet-name>
    </filter-mapping>

    <filter-mapping>
      <filter-name>FlexCacheFilter</filter-name>
      <servlet-name>FlexMxmlServlet</servlet-name>
    </filter-mapping>

    <filter-mapping>
      <filter-name>FlexCacheFilter</filter-name>
      <servlet-name>FlexSwfServlet</servlet-name>
    </filter-mapping>
<!-- End Flex Filter Mapping -->

Add the following under the </listener> of the WebappContextListener:

<!-- Start Flex Listener -->        
    <listener>
        <listener-class>flex.bootstrap.BootstrapListener</listener-class>
    </listener>
<!-- End Flex Listener -->        


<!-- Start Flex servlets -->
    <servlet>
        <servlet-name>FlexProxyServlet</servlet-name>
        <display-name>Flex Web Services Proxy Servlet</display-name>
        <description>Optional proxy for relaying web services messages</description>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.flashproxy.ProxyServlet</param-value>
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>FlexSwfServlet</servlet-name>
        <display-name>SWF Retreiver</display-name>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.swfmanager.SwfServlet</param-value>
        </init-param>
        <!-- SwfServlet must be initialized after MxmlServlet -->
        <load-on-startup>4</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>FlexMxmlServlet</servlet-name>
        <display-name>MXML Processor</display-name>
        <description>Servlet wrapper for the Mxml Compiler</description>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.mxml2.MxmlServlet</param-value>
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>FlexErrorServlet</servlet-name>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.mxml2.ErrorPageServlet</param-value>
        </init-param>
    </servlet>
    
    <servlet>
        <servlet-name>FlexInternalServlet</servlet-name>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.filemanager.FileManagerServlet</param-value>
        </init-param>
        <load-on-startup>10</load-on-startup>
    </servlet>

    <servlet>
        <servlet-name>FlexForbiddenServlet</servlet-name>
        <display-name>Prevents access to *.as files</display-name>
        <servlet-class>flex.bootstrap.BootstrapServlet</servlet-class>
        <init-param>
            <param-name>servlet.class</param-name>
            <param-value>flex.util.ForbiddenServlet</param-value>
        </init-param>
    </servlet>    
    
<!--- End Flex Servlets -->

Add the following under the </servlet-mapping> of the *.do url pattern:

<!-- Start Flex Mappings -->
    <servlet-mapping>
        <servlet-name>FlexMxmlServlet</servlet-name>
        <url-pattern>*.mxml</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>FlexSwfServlet</servlet-name>
        <url-pattern>*.swf</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
        <servlet-name>FlexSwfServlet</servlet-name>
        <url-pattern>*.swd</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>FlexForbiddenServlet</servlet-name>
        <url-pattern>*.as</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>FlexForbiddenServlet</servlet-name>
        <url-pattern>*.swc</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
        <servlet-name>FlexErrorServlet</servlet-name>
        <url-pattern>/flex-error</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
        <servlet-name>FlexInternalServlet</servlet-name>
        <url-pattern>/flex-internal/*</url-pattern>
    </servlet-mapping>
    
    <servlet-mapping>
        <servlet-name>FlexProxyServlet</servlet-name>
        <url-pattern>/flashproxy/*</url-pattern>
    </servlet-mapping>    
        
<!-- End Flex Mappings -->   

Finally add the following just above the </web-app> tag to add Flex JSP tag-lib support to Workshop:

<!-- Start Flex Tag Lib -->
    <taglib>
        <taglib-uri>FlexTagLib</taglib-uri>
        <taglib-location>/WEB-INF/lib/flex-bootstrap.jar</taglib-location>
    </taglib>    
<!-- End Flex Tag Lib -->   

Creating a Test Program

Now that's all done, you'll be wanting to test that everything is working correctly, and for this we'll create a small test program:

1. Right click you <AppName>Web project and choose New -> Other File Types
2. For the filename enter Test.mxml
3. Add the following as the contents of that file and click save:

<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" height="600">

    <mx:Effect>
        <mx:Zoom name="FadeIn" zoomFrom="1" zoomTo="100" duration="1000"/>
        <mx:Fade name="FadeOut" alphaFrom="100" alphaTo="0" duration="1000"/>        
    </mx:Effect>

    <mx:TitleWindow title="It WORKED!" width="200" height="200">
        <mx:Image id="bea" source="@Embed('http://www.bea.com/content/images/bea_logo.gif')"
                           creationCompleteEffect="FadeIn"
                           showEffect="FadeIn"
                           hideEffect="FadeOut"
                           effectEnd="bea.visible = ! bea.visible"
                            />
    </mx:TitleWindow>
</mx:Application>

Testing

To test, simply open a browser and point it at the Test.mxml file. If all has been done correctly, you should see a small pause and then the Initialising bar, after which this program will be displayed.

Have Fun!