Requirements      
Prerequisite knowledge Required products
Sample files User level
To successfully complete this article you should be familiar with a J2EE
application server, Enterprise JavaBeans (EJB), and either Flex Builder
3 or Flash Builder 4.

Flash Builder 4 (Download trial)
 
Intermediate
       

 

 
Additional Requirements

 
Adobe BlazeDS (binary distribution)
When you need to retrieve data from a back-end system and show it in your Flex application, using BlazeDS and Enterprise JavaBeans (EJB) is one of many options available. Flex and BlazeDS, together with the Oracle WebLogic Server, enable you to build a fast, scalable, and high availability enterprise solution based on industry standards.
 
This tutorial uses Flash Builder 4 for Flex application development, Eclipse with the Oracle Enterprise plug-in for the EJB and J2EE web application development, and BlazeDS to connect the Flex application with the J2EE application.
 
After completing this tutorial you can make your own enterprise application, and with Oracle WebLogic you won't have to worry about the performance or availability of your application. Further, because Enterprise JavaBeans is an industry standard, there are plenty of resources and books available to help developers get started.
 
In this article you start by making a WebLogic domain and creating a shared library for WebLogic, which holds the BlazeDS jars. This shared library will be used by the web project.
 
In Eclipse with the Oracle Enterprise Pack plug-in you will make a Java Persistence API (JPA) project with region and countries EJB entities, which are based on the same tables in the sample WebLogic HR database schema. Then you will add an EJB project, which has an EJB Session Bean with a method that returns the regions and their countries. Next you will add a Dynamic Web project to the Eclipse workspace. In this web project you'll add the BlazeDS configuration files, which include a reference to the EJB Session bean, and add the BlazeDS servlet to the web.xml file. The last Eclipse step is to deploy these projects to your WebLogic domain.
 
After setting up the server-side implementation, you'll create a Flex application in Flash Builder 4 that calls the EJB Session Bean method and displays the regions and countries in a grid.
 
In addition to Flash Builder 4 and BlazeDS, you'll need to download and install the following software:
 

 
Making a WebLogic domain

The first step is to a make a new WebLogic domain. This domain will be used for the EJB and the BlazeDS web application.
 
Follow these steps:
 
  1. Run the config.cmd file in the wlserver_10.3\common\bin folder of your WebLogic home.
  2. Select Create A New WebLogic Domain and click Next.
Generating a basic WebLogic domain
 
Figure 1. Generating a basic WebLogic domain
  1. On the Select Domain Source screen, leave the defaults and click Next (see Figure 1).
  2. For the WebLogic Domain name, type demo_domain and click Next.
  3. In the following steps provide a WebLogic administrator password, put the domain in Development Startup Mode, and opt to use the Sun SDK.
  4. In the Select Optional Configuration screen you can change the port numbers or add a managed server. For this demo you don't need to change anything, so just click Next.
  5. Review your settings and click Create to make your WebLogic demo domain.
  6. As the domain is being created, note your Domain Location and your Admin Server URL in the progress dialog box (see Figure 2). You will need this information later on.
  7. Click Done.
 
Figure 2. The Creating Domain dialog box with the domain location and server URL
 

 
Adding a JDBC data source

For the EJB entities you need to add a Java Database Connectivity (JDBC) data source that has a reference to the HR sample schema in the Oracle database.
 
  1. Start the WebLogic demo domain by running startWebLogic.cmd in the user_projects\domains\demo_domain folder of your WebLogic home.
  2. Open a browser and go the WebLogic console application at http://localhost:7001/console.
  3. Log in as the administrator. (This is the administrator account you set up in the WebLogic domain creation wizard; for example, weblogic).
  4. On the overview page, expand Services and then expand JDBC.
  5. Click Data Sources (see Figure 3).
Selecting Data Sources
 
Figure 3. Selecting Data Sources
  1. On the Create A New Data Source page, type hrDS for the name and type jdbc/hrDS for the JNDI name (see Figure 4).
Creating a new JDBC data source
 
Figure 4. Creating a new JDBC data source
  1. Click Next two times.
  2. Next you need to configure the connection properties. If you installed the Oracle Database Express Edition then type xe for the Database Name, localhost for the Host Name, 1521 for the Port, and hr for the Database User Name and password.
  3. Click Next to test the configuration.
Note: If the test fails, check if the hr account is locked (this is default). To correct this, run SQL*Plus (sqlplus), use an Oracle administrator account to connect to your database, and unlock the hr user by executing the following command: alter user hr account unlock;.
 
  1. Select the WebLogic AdminServer as the target for the data source.
  2. Click Finish.
  3. Shutdown the WebLogic server by pressing Ctrl+C in your command window.

 
Making a BlazeDS shared library for WebLogic

WebLogic supports shared libraries, which means you don't need to add the BlazeDS libraries to the WEB-INF/lib folder of every BlazeDS web project. Instead, you only need to add a reference to a shared library in the weblogic-application.xml deployment descriptor. This streamlines BlazeDS web application deployment. Also, you can upgrade the BlazeDS JARs by making a new shared library and use this new shared library in your web projects without changing the web applications.
 
  1. Download and unzip the sample files for this tutorial.
  2. Navigate to the blazeds_lib folder you just unzipped.
  3. In the APP-INF\lib folder, put all the BlazeDS JAR files (you can extract these from the BlazeDS WAR file) and the Peter Martin's EJB and Flex Integration JAR file.
  4. Edit the MANIFEST.MF file in the META-INF folder and update the Specification-version and Implementation-version so it matches your BlazeDS library version. For example:
Manifest-Version: 1.0 Ant-Version: Apache Ant 1.7.0RC1 Created-By: 14.0-b16 (Sun Microsystems Inc.) Extension-Name: blazeds Specification-Version: 4.0 Implementation-Title: BlazeDS - BlazeDS Application Implementation-Version: 4.0.0.13931 Implementation-Vendor: Adobe Systems Inc.
  1. Zip the contents of the blazeds_lib folder. Make sure that this ZIP file contains only the APP-INF and META-INF folders and not the blazeds_lib folder itself.
  2. Change the .zip extension to .ear to create a file named blazeds_lib.ear.
You will need the blazeds_lib.ear file in the BlazeDS web application project.
 

 
Setting up the Eclipse workbench

After you install Eclipse 3.5 Galileo SR1 with Oracle Enterprise Pack (OEPE), follow these steps to initialize the workbench by adding the WebLogic domain and the Database connection:
 
  1. Start Eclipse and choose a workspace folder for your projects.
  2. To add a new server to your workbench, choose File > New > Other. Then select Server > Server and click Next.
  3. Select Oracle WebLogic Server 11gR1 PatchSet 1 and click Next.
  4. Select the wlserver_10.3 folder in your WebLogic home (see Figure 5) and click Next.
Selecting the WebLogic home folder
Figure 5. Selecting the WebLogic home folder
  1. For the Domain Directory select the WebLogic domain you created earlier (demo_domain).
Specifying the domain directory
Figure 6. Specifying the domain directory
  1. Click Finish (see Figure 6).
To generate the HR EJB entities from the database you need to add a database connection to your workbench.
 
  1. Open the Data Source Explorer View by choosing Window > Show View > Other.
  2. Expand Data Management, select Data Source Explorer, and click OK.
  3. In the Data Source Explorer view, right-click Database Connections and select New Connection.
  4. Select Oracle Database Connection as the Connection Profile Type and type hr as the Name.
  5. On the next screen provide the driver and connection details. You can click Test Connection to verify your settings (see Figure 7).
  6. Click Finish.
Specifying connection details
Figure 7. Specifying connection details
  1. In the Data Source Explorer view expand Database Connections, hr, orcl, and Schemas. Next, right-click the HR Schema and select Show In Schema Viewer.
You can now see the countries and regions tables that will be used in this article (see Figure 8).
 
The HR database schema
Figure 8. The HR database schema

 
Creating the EJB entity and Session Beans

The next step is to add a JPA project to the workbench.
 
  1. In Eclipse, choose File > New > Other, expand the JPA node, and select JPA Project.
  2. Click Next.
  3. Type HrModel as the Project Name.
  4. Select Add Project To An EAR and type HrFlexBlazeEAR as the EAR project name (see Figure 9).
You will also add the Session Bean and the web application project to this EAR project.
 
  1. Click Next.
Configuring JPA project settings
Figure 9. Configuring JPA project settings
  1. In the JPA Facet dialog box select hr as the Connection and click Finish (see Figure 10).
Selecting the connection
Figure 10. Selecting the connection
  1. When asked about opening the JPA Perspective, click Yes.
  2. In Project Explorer, right-click your HrModel project and select New > Entities From Tables.
  3. In the Generate Custom Entities dialog box select the Countries and Regions tables of the hr database connection. Click Next.
  4. Type the Package name for the entities, com.adobe.model.entities.hr (see Figure 11).
Specifying the package name for the entities
Figure 11. Specifying the package name for the entities
  1. Click Finish to generate the entities.
You can now explore the generated code in Eclipse by opening the Region.java file for example.
 
You can make changes to the Region entity using the JPA Structure view and JPA Details view (see Figure 12).
 
The JPA Structure view and JPA Details view
Figure 12. The JPA Structure view and JPA Details view
For the EJB Session Bean you will need to add a new Named Query.
 
  1. Select the Region entity in the JPA Structure view.
  2. In the JPA Details view, open the Queries Panel and click Add.
  3. Type FindAllRegions as the Name and Named Query as the Type. Click OK.
  4. In the Query itself type select o from Region o (see Figure 13).
The FindAllRegions query
Figure 13. The FindAllRegions query
Because Region and Country have a reference to each other you need to change the Fetch option of one of the entities to Lazy and the other to Eager, otherwise you will get an endless loop of fetching entities.
 
  1. In this case expand the Country entity in the JPA Structure view, select the Region attribute, and set the Fetch option to Lazy (see Figure 14).
Setting a Lazy Fetch on the Region attribute of Country
Figure 14. Setting a Lazy Fetch on the Region attribute of Country
  1. In the JPA Details view for the Region entity, set Fetch to Eager (see Figure 15).
Setting an Eager Fetch on the Region entity
Figure 15. Setting an Eager Fetch on the Region entity
Because this model will be used in the WebLogic application server, you need to change the Transaction type and add the JNDI name of your WebLogic JDBC data source to the persistence.xml configuration.
 
  1. In Project Explorer, open persistence.xml and select the Connection tab.
  2. Use Default (JPA) as the Transaction Type and type jdbc/hrDS as the JTA Data Source Name (see Figure 16).
Setting the transaction type and JTA data source
Figure 16. Setting the transaction type and JTA data source
The next step is to create an EJB project where you will add an EJB Session Bean, which will have a method that returns all the Regions with their Countries.
 
  1. Choose File > New > Project, expand EJB, and select EJB Project to add a new EJB Project to the workbench.
  2. Type HrEJB as the Project Name and select 3.0 as the EJB Module Version.
  3. Select Add Project To An EAR (see Figure 17) and then select the HrFlexBlazeEAR project.
  4. Click Next.
Defining the new EJB project
Figure 17. Defining the new EJB project
  1. Select Create An EJB Client JAR Module.
  2. Click Finish (see Figure 18).
Specifying the EJB client JAR
Figure 18. Specifying the EJB client JAR
  1. In Project Explorer, expand HrEJB and Deployment Descriptor: HrEJB.
  2. Right-click Session Beans and click New > Session Bean (EJB 3.x) to create a new Session Bean.
  3. Choose Stateless as the State Type and enable the local and remote interface (see Figure 19).
  4. Click Next.
Configuring the Session Bean
Figure 19. Configuring the Session Bean
  1. Type HrSession as the Mapped Name (see Figure 20).
  2. Click Finish.
Setting the Session Bean mapped name
Figure 20. Setting the Session Bean mapped name
This Session Bean will return the Region and its Countries. For this you need to add the HrModel to the Java Build Path of the EJB Session and EJB Client project.
 
  1. Right-click the HrEJB project and select Properties.
  2. Select Java Build Path and click the Projects tab.
  3. Click Add to add HrModel (see Figure 21).
  4. Repeat the three previous steps for the HrEJBClient project.
Configuring the Java Build Path
Figure 21. Configuring the Java Build Path
  1. Open the Session Bean where you add the EntityManager with PersistenceContext annotation (HrSessionBean.java). The HrModel in the PersistenceContext annotation must match the model in the persistence.xml file of the HrModel project.
  2. Add the getRegionsFindAll() method to the Session Bean (HrSessionBean.java):
Public List<Region> getRegionsFindAll() { Return em.createNamedQuery("findAllRegions").getResultList(); }
  1. Add this method to the local and remote interface in HrSessionBeanRemote.java and HrSessionBeanLocal.java. (See the sample files for an example.)
Before moving on to the web application development you'll want to test the Session Bean.
 
  1. To deploy your EAR project to the WebLogic Server, right-click HrFlexBlazeEAR in Project Explorer and select Run As > Run on Server.
  2. Select the Oracle WebLogic Server at localhost and click Finish.
  3. Check the console window for the WebLogic server output. There should be no errors.
In the EJB Client project you can add a new Java class to test the Session Bean (see the sample file HrTestClient.java). If you don't know the JNDI name of your remote interface, you can find it by looking at the JNDI tree in the server part of the WebLogic console application. Browse to http://localhost:7001/console , click Servers, and then select the Admin server.
 
When you run the Java test application it will display a list of regions and countries (see Figure 22). If you encounter problems, you can compare your JAVA files against the JAVA files provided in the java folder of the sample files for this article.
 
Test output
Figure 22. Test output

 
Creating the J2EE web application

Follow these steps to create the web application:
 
  1. In Eclipse, choose File > New Project. Expand Web, select Dynamic Web Project, and click Next.
  2. Type HrWeb as the Project Name.
  3. Select Add Project To An EAR and select HrFlexBlazeEAR (see Figure 23).
  4. Click Next
Configuring the new Dynamic Web project
Figure 23. Configuring the new Dynamic Web project
  1. For the Context Root type HrWeb and for the Content Directory type WebContent.
  2. Select Generate Web.xml Deployment Descriptor.
  3. Click Finish.
Make a note of the Context Root; you'll need it for the Flash Builder project.
 
  1. Open the web.xml file and click the Source tab.
  2. Add the BlazeDS MessageBrokerServlet:
<servlet> <servlet-name>MessageBrokerServlet</servlet-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> <servlet-mapping> <servlet-name>MessageBrokerServlet</servlet-name> <url-pattern>/messagebroker/*</url-pattern> </servlet-mapping> <listener> <listener-class>flex.messaging.HttpFlexSession</listener-class> </listener>
  1. For the BlazeDS configuration files, add a new folder called flex under the WEB-INF folder.
  2. In the flex folder, create two XML files named services-config.xml and remoting-config.xml.
  3. Edit services-config.xml and add the code below.
This file is the main BlazeDS configuration, and it's used to define the channels, the factories (in this case the EJB factory), and the other BlazeDS configuration files.
 
<?xml version="1.0" encoding="UTF-8"?> <services-config> <services> <service-include file-path="remoting-config.xml"/> <default-channels> <channel ref="my-amf"/> </default-channels> </services> <factories> <factory id="ejb3" class="com.adobe.ac.ejb.EJB3Factory"/> </factories> <channels> <channel-definition id="my-amf" class="mx.messaging.channels.AMFChannel"> <endpoint url="http://{server.name}:{server.port}/{context.root}/messagebroker/amf" class="flex.messaging.endpoints.AMFEndpoint"/> <properties> <polling-enabled>false</polling-enabled> </properties> </channel-definition> </channels> <logging> <target class="flex.messaging.log.ConsoleTarget" level="Error"> <properties> <prefix>[Flex]</prefix> <includeDate>false</includeDate> <includeTime>false</includeTime> <includeLevel>false</includeLevel> <includeCategory>false</includeCategory> </properties> </target> </logging> </services-config>
  1. Edit remoting-config.xml and add the code below.
The hrEJB destination defines the local JNDI name of your HR Session Bean.
 
<?xml version="1.0" encoding="UTF-8"?> <service id="remoting-service" class="flex.messaging.services.RemotingService"> <adapters> <adapter-definition id="java-object" class="flex.messaging.services.remoting.adapters.JavaAdapter" default="true"/> </adapters> <default-channels> <channel ref="my-amf"/> </default-channels> <destination id="hrEJB"> <properties> <factory>ejb3</factory> <source>HrSession#com.adobe.model.hr.services.HrSessionBeanRemote</source> </properties> </destination> </service>
The web project is almost ready for deployment, now you just need to add a reference to the BlazeDS library.
 
  1. Expand your EAR project, then expand EarContent and META-INF, and open the weblogic-application.xml file.
This file is the WebLogic application deployment descriptor and contains the shared libraries references.
 
  1. Select the Shared Libraries node and click Add Shared Library References (see Figure 24).
Adding a shared library reference
Figure 24. Adding a shared library reference
  1. When you see the list of WebLogic shared libraries, click Manage WebLogic Shared Libraries (see Figure 25).
WebLogic shared libraries
Figure 25. WebLogic shared libraries
  1. Click Add, select the BlazeDS shared library (see Figure 26), and click OK.
Adding a WebLogic shared library
Figure 26. Adding a WebLogic shared library
  1. Select the blazeds library in the weblogic-application.xml deployment descriptor (see Figure 27).
Selecting the blazeds shared library
Figure 27. Selecting the blazeds shared library
  1. In Project Explorer, right-click the EAR project (HrFlexBlazeEAR) and select Run As > Run On Server to deploy this project to the WebLogic server.

 
Creating the Flex application in Flash Builder

The last step is to make the Flex application and see the results.
 
  1. In Flash Builder, choose File > New > Flex Project.
  2. Type HrFlexApp for the Project Name, select J2EE as the Application Server Type, and select BlazeDS as the remote object access service to use (see Figure 28).
  3. Click Next.
Creating a new Flex project
Figure 28. Creating a new Flex project
  1. For the Root Folder specify the WebContent folder of your Hr web project.
  2. For the Root URL use http://localhost:7001/HrWeb.
  3. For the Context Root type HrWeb.
  4. Click Validate Configuration and then click Finish (see Figure 29).
Configuring the J2EE server for the project
Figure 29. Configuring the J2EE server for the project
In the Flex project you also need to create the Region and Country entities in a package called entities.
 
  1. Right-click the src package and select New > Package.
  2. Type entities for the Name and click Finish.
  3. Right-click entities and select New > ActionScript class.
  4. Type Country for the Name and click Finish.
  5. Repeat the previous two steps to create the Region ActionScript class.
  6. Insert the following code into the Region.as class.
RemoteClass is mapped to the Java Region entity class and the countries variable is an ArrayCollection.
 
package entities { import mx.collections.ArrayCollection; [Bindable] [RemoteClass(alias="com.adobe.model.entities.hr.Region")] public class Region { public function Region() { } public var regionId:Number; public var regionName:String; public var countries:ArrayCollection; } }
  1. Insert the following code into the Country.as class.
This class also has a reference to the Country Java class and the region variable is a Region type.
 
package entities { [Bindable] [RemoteClass(alias="com.adobe.model.entities.hr.Country")] public class Country { public function Country() { } public var countryId:Number; public var countryName:String; public var region:Region; } }
Next you need to create the user interface with data grids to display the regions and countries. Before you can display this data, however, you need to add a remote object with its destination attribute set to hrEJB . This value must match the destination in the remoting-config.xml file in your web project. The RemoteObject must be defined in the fx:Declarations element because it is not a user interface component.
 
  1. Edit HrFlexApp.mxml and add the code as shown below:
<fx:Declarations> <mx:RemoteObject id="srv" showBusyCursor="true" destination="hrEJB"/> </fx:Declarations> <s:applicationComplete> <![CDATA[ srv.getRegionsFindAll(); ]]> </s:applicationComplete>
The code within the applicationComplete element invokes the RemoteObject (in this case the EJB Session Bean) and calls the getRegionsFindAll method.
 
The last step is to display the Regions in a grid and the Countries in a second grid.
 
  1. Add the following code to HrFlexApp.mxml to define the user interface:
<s:Panel x="30" y="0" width="525" height="446" title="EJB Example with BlazeDS on WebLogic"> <mx:DataGrid id="regions" dataProvider="{srv.getRegionsFindAll.lastResult}" width="500" y="10" x="10"> <mx:columns> <mx:DataGridColumn dataField="regionId" headerText="Region Id"/> <mx:DataGridColumn dataField="regionName" headerText="Region Name"/> </mx:columns> </mx:DataGrid> <mx:DataGrid id="countries" dataProvider="{regions.selectedItem.countries}" y="200" width="500" x="10"> <mx:columns> <mx:DataGridColumn dataField="countryId" headerText="Country Id"/> <mx:DataGridColumn dataField="countryName" headerText="Country Name"/> </mx:columns> </mx:DataGrid> </s:Panel>
The dataprovider on the regions DataGrid is bound to the RemoteObject method call's result.
 
  1. Choose Run > Run HrFlexApp to run your project and you should see the data displayed in the data grids (see Figure 30).
The completed application
Figure 30. The completed application
If you encounter problems, you can check your source code against the HrFlexApp.mxml, Country.as, and Region.as files provided in the flex folder of the sample file.
 

 
Where to go from here

Using BlazeDS, EJBs, and the WebLogic Application Server you've constructed reliable and scalable enterprise solution for your J2EE Flex application. Along the way, you saw how the Oracle Enterprise Pack for Eclipse and Flash Builder 4 can help you develop more productively.
 
Here are some additional resources for further reading: