Prerequisites

This article is for Flex developers who want to integrate their applications with WebSphere Portal. It assumes that you are familiar with Flex at a basic programming level and that you are familiar with Java™ programming. It also assumes that you have administrative access to a working WebSphere Portal server for the relevant portions of the article. It does not, however, assume that you are familiar with programming or administering WebSphere Portal.

Along with this article, you will need the following tools installed to make sure the sample case works well.

• Adobe Flex Builder — This article is written with Adobe Flex Builder 3. Of course, you can do it with the appropriate JDK and a text editor, but the amount of extra work is significant.
• WebSphere Portal V6.0.1 or higher — If you are using WebSphere Portal V6.0, you should update your WebSphere Portal V6 environment. (See Resources.)
• IBM Rational Software Architecture v7.0.0
• IBM DB2 Enterprise v9.1

Back to top

Overview of sample application

Let's briefly look at the business requirements of this sample application called TODOList. Many users want to keep records for their appointments, anniversaries, reminders, or any events. And they need to conveniently view their coming items, create new items, and delete any items if possible. Can we provide a smart tool to help them? In this article, we will show you how to build the application in a process that is similar to the way most developers create applications in order to illustrate the complete development procedures.

Figure 1 below shows the sample application infrastructure. We will quickly state the technical aspects of the sample before building the actual application with Adobe Flex and IBM WebSphere Portal. The whole application will be built in a WAR file, including presentation layer and business layer modules, although they are developed in the different projects.

The top rectangle represents a Flex project as the presentation layer that is built by MXML and ActionScript, while the bottom rectangle represents a Java project as the business layer that is built by Java and JDBC. The Flex application calls a Java service through a RemoteObject that is one of the remote procedure call (RPC) components provided by Flex. In this sample application, we will import BlazeDS to implement the remote object.

Back to top

Build Flex project

Adobe Flex is a highly productive, free, open source framework for building and maintaining expressive Web applications that deploy consistently on all major browsers, desktops, and operating systems.

It consists of a rich component library with more than 100 proven, extensible UI components for creating RIAs. It also provides a standard-based language and programming model that supports common design patterns. MXML, a declarative XML-based language, is used to represent UI layout and behaviors, and each MXML file is a separate component. ActionScript, a powerful object-oriented programming language, is used to create client logic. ActionScript provides flow control and object manipulation features that are not available in MXML. Flex 3 was released at the end February 2008, and you can learn more about Flex 3 features from the Adobe Flex Web site. (See Resources.)

Flex applications can be built only by the free Flex SDK, which comprises the Flex framework (component class library) and Flex compiler, enabling you to freely develop and deploy Flex applications using an IDE of your choice. Developers can use Adobe Flex Builder 3 to dramatically accelerate development.

The Flex wizard guides you on how to quickly and easily create this sample in Flex Builder 3.

1. Open Flex Builder 3, and select File --> New --> Flex Project.
2. Enter TODOListFlex as the project name.
3. Select the default location, which is the workspace, as the project location.
4. Choose Web application as the application type.
5. For the application server type, you may follow the steps in Adobe Flex 3 Help\Using Flex Builder 3\Flex Builder Basic\Working With Projects if you have a server. But in this sample, we select None, as the Figure 2 screen shot shows, because we don't need that.

6. Keep all default settings for this Flex application and the build paths in the next two configuration pages.
7. Click Finish to create this project.

Then, Flex Builder 3 will generate a primary MXML with the same name of new project. This application includes a MXML file, which starts with the <mx:Application> root tag, as follows in Listing 1.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
</mx:Application>
            

In this section, you only need to care about the main file, TODOListFlex.mxml. You can use the Flex navigator view to import other resources (MXML, ActionScript, and Image) into the project from our sample code. A view of the project category is shown below in Figure 3.

The MXML editor in Flex Builder 3 allows you to work in either Source or Design mode at the top of the editor area. Make sure that you are in Source mode, and then add a <mx:Panel> component as the child of the main application to represent UI layout, and place a <mx:VBox> component in this panel to make it lay in vertical. See Listing 2.

<mx:Panel title="TODO List" width="100%" height="100%" 
   paddingLeft="4" paddingTop="8" paddingRight="8" paddingBottom="4">
   <mx:VBox width="100%">
   </mx:VBox>
</mx:Panel>

Put a <mx:DataGrid> component between <mx:VBox> tags to list all to-do items. We define an ArrayCollection todoItemColl and assign it as the dataProvider for the DataGrid. (See Listing 3.) We will call RemoteObject service to obtain data for this ArrayCollection in the section, "Use RemoteObject in Flex."

<mx:DataGrid id="todoListDG" dataProvider="{todoItemColl}">
   <mx:columns>
   <mx:DataGridColumn visible="false" dataField="id"/>
   <mx:DataGridColumn width="100" headerText="Date" dataField="deadlineStr"/>
   <mx:DataGridColumn width="400" headerText="Subject" dataField="task"/>
   ...
   </mx:columns>
</mx:DataGrid>

There is a form under the VBox to allow users to add new to-do items. The form contains three text fields (such as Date, Subject, and Owner) and a button. We use a <mx:Grid> component here to control the UI alignment. (See Listing 4.)

<mx:Grid>
   <mx:GridRow>
      <mx:GridItem> 
         <mx:Label text="Date:"/>
      </mx:GridItem>
      <mx:GridItem>
         <mx:DateField id="deadlineDateField" formatString="YYYY-MM-DD"/>
      </mx:GridItem>
   </mx:GridRow>
   ...
   <mx:GridRow>
      <mx:GridItem colSpan="2" horizontalAlign="right">
         <mx:Button label="Add" click="saveNewItem()"/>
      </mx:GridItem>
   </mx:GridRow>
</mx:Grid>

Then we create client logic with ActionScript codes within a <mx:Script> tag and wrap the contents in a CDATA construct. (See Listing 5.) To access the different data sources, we define a constant, USE_MOCK_DATA, to control whether the application accesses remote data or local mock data. Now we set the constant value to be true because we are just showing it as a separate application for now. We will elaborate on how to use RemoteObject Service to assess data in the section, "Use RemoteObject in Flex."

<mx:Script>
   <![CDATA[
      …
      private static const USE_MOCK_DATA:Boolean = true;	…
      private function getTodoList():void
      {
         if(USE_MOCK_DATA) {
            // Creat the mock data
         }
         else {
            // Use remote object to access the back-service
         }
      }
      …
   ]]>
</mx:Script>

You will find more sample code in the attachment. (See Downloads.) After the above steps, select TODOListFlex.mxml and click the Run button at the toolbar. Flex Builder will compile this application and show the below pages, as in Figure 4.

Back to top

Build portal project

WebSphere Portal is a framework that lets you plug in new features or extensions called portlets. Portlets are applications within WebSphere Portal, which are the encapsulation of reusable components that combine Web-based content, application functionality, and access to resources.

WebSphere Portal, starting with Version 5.0.2.1, provides a runtime environment for both JSR 168 Portlet API and IBM Portlet API. JSR 168 is a specification from the Java Community Process for the standardization of portlets. The specification was developed to provide interoperability for running portlets on any vendor's implementation of the JSR 168 portlet container. The IBM Portlet API is now deprecated in WebSphere Portal V6.0 in order to show IBM's commitment to the JSR 168 standard portlet API. Also, many new functions will only be available to standard portlets. We will use the JSR 168 standard portlet in our sample.

This section shows how to create a new portlet project using the Rational Software Architecture (RSA) wizard. (See Figure 5.)

1. Open RSA, and select File --> New --> Project.
2. Select Portlet Project to create a project.
3. Enter TODOList as the project name.
4. Target runtime should be WebSphere Portal V6.0 stub.
5. Portlet API should be JSR 168 Portlet.
6. Select the checkbox of "Create a portlet".
7. Make sure the Basic Portlet is selected as Portlet type.
8. Click Next, leaving all fields as default.
9. Click Finish to create the portlet project.

After you finish the above steps, the project category should look like Figure 6.

Actually, you can deploy this portlet on your portal server now. But we will integrate the Flex application created in the previous section into the portlet project first.

Back to top

Integrate Flex into the portlet project

To integrate the Flex application into our portlet project we must complete a few steps.

Introducing Web-tier compiler

The Flex compiler creates SWF files that run in Adobe Flash Player. Flex offers several kinds of compilers: the Web-tier compiler, the mxmlc command-line compiler, and the Flex Builder project compiler. In this article, we will use the Web-tier compiler, which is a set of servlets and servlet filters that run in a J2EE application server. The application server passes on requests from *.mxml files to the servlet container, which then compiles into a SWF file and returns the results to the client. In this case, it allows you to simply copy the Flex files into a directory visible to your server, and the flex codes will be compiled automatically when you request the main application file using your Web browser. This also allows you to rapidly compile, test, and deploy an application instead of compiling your MXML files into a SWF file and then deploying its wrapper files on a Web server.

You should download the FlexModule_J2ER from the Adobe open source Web site if you have not already. Do the following steps to introduce it into this sample portlet project.

1. Unzip the webtier.war file to a directory called webtier.
2. Copy flex-bootstrap.jar and flex-bootstrap-jsp.jar from the webtier\WEB-INF\lib to the corresponding WEB-INF\lib directory of the portlet project.
3. Copy all files and directories from the webtier\WEB-INF\flex directory to the corresponding WEB-INF\flex directory of the portlet project.
4. Update web.xml file content in the WEB-INF\ directory of the portlet project according to the web.xml file in the webtier\WEB-INF (You can copy the web.xml from the sample code which we have updated accordingly -- see Downloads).

Introducing BlazeDS

The Flex SDK contains features for accessing server-side data. These components use RPC to interact with server environments to provide data to Flex applications and send data to back-end data sources.

Three kinds of RPC components are supported by Flex: HTTPService, WebService, and RemoteObject. A client-side RPC component calls a remote service and then stores the response data in an ActionScript object where you can easily obtain the data.

RemoteObject

We use the RemoteObject component in this sample because it lets you access business logic directly in its native format rather than formatting it as XML, as you do with HTTPService or WebService. This saves you the time required to expose existing logic as XML. The Flex application can access a Java object directly by remote invocation of a method on a designated object. Those objects on the server can then deal with its native data types as arguments, query a database from those arguments, and return its native data types as values.

Another benefit of RemoteObject services is the speed of communication across the wire. Data exchanges still happen over HTTP or HTTPS, but the data itself is serialized into the Action Message Format (AMF), which is a binary format for data serialization/deserialization and remote method invocation. It improves performance by dramatically compressing the size of data transferred and parsing binary data into objects in memory far more efficiently than parsing XML data.

Using BlazeDS

BlazeDS is an Adobe open source project that employs RemoteObject component to access remote Java objects. It contains configurable channels that transport the data between the client and server and can run on a J2EE application server.

You can download the BladeDS package from the Adobe open source Web site. (See Resources.) Do the following steps to enable this portlet application to use BlazeDS:

1. Unzip the blazeds.war to a directory called blazeds.
2. Copy all jar files from blazeds\WEB-INF\lib to the WEB-INF\lib directory.
3. Copy all configuration files from the blazeds\WEB-INF\flex directory to the WEB-INF\flex directory of this application. Overwrite if there are existing ones.
4. Define MessageBrokerServlet and a session listener in WEB-INF\web.xml of this portlet application, as below in Listing 6. You can skip this step if you copied the web.xml from our sample code.

<!-- Http Flex Session attribute and binding listener support -->
<listener>
   <listener-class>flex.messaging.HttpFlexSession</listener-class>
</listener>
	
<!-- MessageBroker Servlet -->
<servlet>
   <servlet-name>MessageBrokerServlet</servlet-name>
   <display-name>MessageBrokerServlet</display-name>
   <servlet-class> flex.messaging.MessageBrokerServlet </servlet-class>

   <init-param>
      <param-name>services.configuration.file</param-name>
      <param-value>/WEB-INF/flex/services-config.xml</param-value>
   </init-param>

   <load-on-startup>1</load-on-startup>
</servlet>
         

Copy Flex code into the portlet project

Copy all files under the src directory from the Flex project to the directory, WebContent/_TODOList/jsp/html. The category of the portlet project should look like Figure 7.

Create Java RemoteObject class

For simplicity, we need only one Java RemoteObject class, TodoItemRO, as the remote business service. You can copy the Java source code and the jdbc.properties file from the sample code (WEB-INF\src) to the portlet project. TodoItem is the only entity Java bean in this sample. (See Figure 8.)

Configure RemoteObject in portal

Flex finds the remote services according to its configuration file, services-config.xml, in the WEB-INF\flex. You need to specify the fully qualified class name in the source property of a remoting service destination in the BlazeDS services-config.xml file, or a file that it includes by reference, such as the remoting-config.xml file. The class also must have a no-arg constructor which will be used by Flex to instantiate an instance. We configured the single Java RemoteObject in the remoting-config.xml file which is in WEB-INF\flex, as below in Listing 7.

<destination id= ‘todoItemRO’>
   <properties>			 
      <source> todolist.ro.TodoItemRO </source>
   </properties>
</destination> 
            

Use RemoteObject in Flex

Now that we have created and configured the remote object, it's time to use it as a remote service.

First, create a RemoteObject component in TODOListFlex.mxml with a unique ID, srvTODOList. The value of the destination should match the destination entry in the WEB-INF\flex\remoting-config.xml file in the portal project. In this sample, it is todoItemRO. (See Listing 8.)

<mx:RemoteObject id="srvTODOList" destination="todoItemRO" showBusyCursor="true" 
requestTimeout="10"/>
           

Next, create an AsyncToken object to call the Java method defined in the destination service using the unique ID of the RemoteObject component. The AsyncToken class provides a place to set additional or token-level data for asynchronous RPC operations.

It also allows an IResponder to be attached for an individual call (or, callback method). We define a simple responder class, TokenResponder, that implements the IResponder Interface (see the code sample, TODOListFlex\src\util\TokenResponder.as). It will call the specified callback method when Java returns or raises a specified alert as the handler of any fault. We add it as the responder of the AsyncToken object, get the response data, and transform it into a Flex variable type. (See Listing 9.)

var asyncToken:AsyncToken = AsyncToken(srvTODOList.getTodoItems());
asyncToken.addResponder(new TokenResponder(displayTodoItems, "Error Getting TODO List"));

private function displayTodoItems(event:ResultEvent):void
{
   todoItemColl = event.result as ArrayCollection;
   todoItemColl.refresh();
}
           

Include Flex component in JSP

The Flex compiler module for J2EE application servers also provides a JSP tag library that lets you include Flex applications in JSPs. Add the following tag library declaration to your JSP page to import Flex 3 Tag Library in JSP: WebContent\_TODOList\jsp\html\TODOListPortletView.jsp. (See Listing 10.)

<%@ taglib uri="FlexTagLib" prefix="mm" %>

You can either refer a separate MXML file or include MXML syntax directly in the JSP by the <mm:mxml> tag. (See Listing 11.)

<mm:mxml source="TODOListFlex.mxml" width="100%" height="768">
</mm:mxml>

You can delete all old content of the JSP which is generated by RSA. You can refer to the JSP in the sample code.

Back to top

Deployment

Make use of the J2EE Web application archive feature in RSA to export a WAR file so that you can install on a staging or production portal server.

Make sure that the constant USE_MOCK_DATA in the WebContent\_TODOList\jsp\html\TODOListFlex.mxml file has been set to false in order to use RemoteObject to get TODO list. Copy the DB2 JDBC driver jars from sample code to the WEB-INF\lib.

Do the following steps to export the WAR file from this sample project.

1. Right-click this sample project name and select Export from the pop-up menu.
2. Select WAR file in the Export window, and then select Next.
3. Specify a location for the new WAR file.
4. Click Finish and make sure you can find the WAR file under the location.

Log on to WebSphere Portal Server with the administrator role, and go to the Administrative page to install the WAR file by following these steps.

1. If it's not already running, start the portal server. From the control panel select Portlet Management , Web Modules.
2. On the "Manage Web Modules" page, click Install.
3. On the "Installing a Web module" page, use the Browse button to locate the WAR file. Click Next and Finish. This step may take several minutes due to the large size. You can reduce the size of the WAR using shared lib. (Refer to the section, "Reduce WAR size".)

After installing the portlet, we need to place it into a page. From the Administrative page of the portal server do the following steps.

1. Navigate to Portal --> User Interface --> Manage Pages.
2. Locate the page to add a portlet and click Edit Page Layout.
3. Add the portlet (TODOList) in the page, and click Done to save the changes.

Now go the page and verify the TODOList portlet.

If you host your portal server on a Linux® system (skip this section if you are using a Windows® system), the flash may not be displayed. You may need to configure the java.awt.headless parameter for JVM of portal server as value of true. Follow these steps to do so:

1. Start the WebSphere Application Server: /opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
2. Open the WebSphere Application Server Administrative Console: http://server:10001/ibm/console
3. Navigate to Server --> Application Server --> WebSphere_Portal --> Process Definition --> Java Virtual --> Custom Properties

4. Restart the WebSphere Application Server and Portal Server.

Back to top

Reduce WAR size (shared lib)

This step is optional. Because the size of the WAR may be larger than 20MB, you can move some of the contents into the WebSphere Application Service shared lib in order to reduce the size. Refer to the section, "Create a shared library", in the developerWorks article, "Using resource environment providers in WebSphere Application Server". (See Resources.)

Back to top

Summary

This article covered the major features and enhancements during the integration development between Adobe Flex and WebSphere Portal. We also examined the runtime environment used to show the sample application and how easy it can be to create an RIA application and integrate Portal features before delivering the applications for an improved user experience.

Back to top

Download

Information about download methods

Resources

Learn

• On the Adobe Flex main page, find a Flex overview and information on design pattens.
  
  
• Take a quick tour of the Flex world with Getting Started with Flex 3 (PDF).
  
  
• Read more articles about Flex from Flex cookbook (beta).
  
  
• See the article, "Using resource environment providers in WebSphere Application Server", for more information about how to reduce the WAR size.
  
  
• Read "IBM Rational Application Developer V6 Portlet Application Development and Portal Tools" for more information about portlet development with Rational Tools.
  
  
• Read more articles from the WebSphere Portal zone and the Web development zone.
  
  

Get products and technologies

• Upgrade the WebSphere Portal Version 6.0 refresh pack 1.
  
  
• Download Webtier Compiler and BlazeDS to integrate Flex and Portal.