We'd really like to hear from you if you have any ideas or opinions on the type of thing we should be including.

In addition to this, you can use the 'ActionScript Adapter' for messaging, which means that messages can be passed between Flex clients without the need of JMS, this would be a potential solution, if you did not need to integrate with any other systems via JMS.

We have used this in anger and it works well. I hope SecureDestinationLocator will make the next Cairngorm release, but in the mean time, you can get the code from Peter's Blog or check out his presentation at MAX.

[RemoteClass(alias="java.package.structure.classname")]

We can change the log level of the gateway and take a look at what it is up to.

In services-config.xml, change the log level from Error to Debug as below:

   <logging>

      <target class="flex.messaging.log.ConsoleTarget" level="Debug">

The output below occurs the first time a call is made from the client, it's just checking that the endpoint is still available, don't expect to see this every call.

12:16:14,805 INFO  [STDOUT] [Flex] Deserializing AMF/HTTP request

Version: 3

  (Message #0 targetURI=null, responseURI=/1)

    (Array #0)

      [0] = (Typed Object #0 'flex.messaging.messages.CommandMessage')

        operation = 5

        messageRefType = null

        correlationId = ""

        messageId = "8DA9ED25-7DA2-0175-16F8-5D4D2EF8E163"

        headers = (Object #1)

        timestamp = 0

        body = (Object #2)

        clientId = null

        destination = ""

        timeToLive = 0

12:16:14,837 INFO  [STDOUT] [Flex] Serializing AMF/HTTP response

Version: 3

  (Message #0 targetURI=/1/onResult, responseURI=)

    (Typed Object #0 'flex.messaging.messages.AcknowledgeMessage')

      destination = null

      headers = (Object #1)

      correlationId = "8DA9ED25-7DA2-0175-16F8-5D4D2EF8E163"

      messageId = "2FC970B5-9518-4649-21E9-ED57D3A627EC"

      timestamp = 1.152616574821E12

      clientId = "2FC970B5-950E-1903-993A-5EB4299C54B5"

      timeToLive = 0.0

      body = null

Next you will see our request to the remote object:

12:16:14,852 INFO  [STDOUT] [Flex] Channel endpoint my-amf received request.

12:16:14,868 INFO  [STDOUT] [Flex] Deserializing AMF/HTTP request

Version: 3

  (Message #0 targetURI=null, responseURI=/2)

    (Array #0)

      [0] = (Typed Object #0 'flex.messaging.messages.RemotingMessage')

        operation = "addAddress"

        source = null

        messageId = "D9F1547F-D5A7-4C11-E53D-5D4D2ED818F1"

        headers = (Object #1)

          DSEndpoint = "my-amf"

        timestamp = 0

        body = (Array #2)

          [0] = (Typed Object #3 'fdsweb.AddressVO')

            line2 = "The Street"

            line1 = "44"

            postalCode = "EH11 9DQ"

            city = "EDINBURGH"

        clientId = null

        destination = "addressBookDelegate"

        timeToLive = 0

Remember that the data does not get transmitted in textual format, it gets sent in binary AMF, this is just the output from the gateway logging after it has received it.

Next we see the gateway calling the remote object and the results from that call:

12:16:14,868 INFO  [STDOUT] [Flex] Adapter 'java-object' called 'fdsweb.AddressB
ookDelegate.addAddress(java.util.Arrays$ArrayList (Collection size:1)
  [0] = fdsweb.AddressVO
    postalCode = EH11 9DQ
    line1 = 44
    line2 = The Street
    city = EDINBURGH

)'

12:16:14,868 INFO  [STDOUT] [Flex] Result: 'java.util.Vector (Collection size:1)


  [0] = fdsweb.AddressVO

    postalCode = EH11 9DQ

    line1 = 44

    line2 = The Street

    city = EDINBURGH

)'

And finally we see the response about to go back to the client:

12:16:14,868 INFO  [STDOUT] [Flex] Serializing AMF/HTTP response
Version: 3
  (Message #0 targetURI=/2/onResult, responseURI=)
    (Typed Object #0 'flex.messaging.messages.AcknowledgeMessage')
      destination = null
      headers = (Object #1)
      correlationId = "D9F1547F-D5A7-4C11-E53D-5D4D2ED818F1"
      messageId = "2FC97128-541C-9D37-38F6-21D302743239"
      timestamp = 1.152616574868E12
      clientId = "2FC97128-540D-3181-BC10-60C5D327A94E"
      timeToLive = 0.0
      body = (Externalizable Object #2 'flex.messaging.io.ArrayCollection')
        (Array #3)
          [0] = (Typed Object #4 'fdsweb.AddressVO')
            postalCode = "EH11 9DQ"
            line1 = "44"
            line2 = "The Street"
            city = "EDINBURGH"

The flex debugging provided in Eclipse is very similar to the java debugging and is intuitive for anyone who has ever used the java debugger. For the full details on debugging in Flex Builder, see the docs, for now you are good to go if you can just set a breakpoint as in the java debugger.

If you want to debug the remote object running in JBoss, you can set up JPDA (Java Platform Debugger Architecture). This allows Eclipse to connect to JBoss by way of sockets and exchange debugging information necessary for the java debugger.

Setting up JPDA in JBoss is actually very simple, all you need to do is:

a) stop JBoss
b) copy the [jboss root]/bin/run.bat to [jboss root]/bin/run_debug.bat (Unix/Linux users change as necessary)
c) in run_debug.bat, uncomment this line:

rem JPDA options. Uncomment and modify as appropriate to enable remote debugging.

rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%

rem JPDA options. Uncomment and modify as appropriate to enable remote debugging.

set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%

From the above techniques, you should be able to set a breakpoint in the Flex code and the java code and watch the gateway debug output, this will give you end to end debugging.

Under the src/fdweb directory of your project, create a java class called AddressBookDelegate and populate it with the code here, this class will be the remote object we are going to call. You will notice in the addAddress method, that we pass in an AddressVO and we pass back a List of AddressVOs, we don't have to pass back Lists, it is just satisfying the functionality we need.

Under your project directory, at the same level as META-INF and WEB-INF, create a folder called 'fdsweb' and inside it create a new ActionScript class using File>New>ActionScript class. Call it AddressVO.as and add the following code in:

package fdsweb
{
   [Bindable]
   [RemoteClass(alias="fdsweb.AddressVO")]
  	
   public class AddressVO
   {			
      public var line1 : String;
      public var line2 : String;
      public var city : String;
      public var postalCode : String;
	
   }
}

In a real project, this directory would probably be com.company.project.etc and is where you will hold all your ActionScript code, but today we will just have a simple package structure.

What the above code shows is that we have a value object (DTO) which has four attributes all of which are Strings, however, as a java developer you probably would have worked this out for yourself as AS syntax is relatively similar to Java. Notice however in ActionScript, you have to declare the package using a brace notation. The main thing to be aware of here is that we are telling the gateway (the component that does the flex-java-flex mapping) that we would like this class to map to our java class AddressVO (in java package fdsweb).

Next we should create the java class, just create a standard java value object, take a look here if you want a sanity check. The java class does not need to be serializable, however, it must have a no-args constructor.

Now we just need to add in the destination which tells the gateway about the remote java object, add the following:

to your remoting-config file, under WEB-INF/flex:

   <destination id="addressBookDelegate">

      <properties>

         <source>fdsweb.AddressBookDelegate</source>

         <scope>application</scope>

      </properties>

   </destination>

As mentioned earlier the flex gateway is responsible for translating java to ActionScript and ActionScript to java, it copies across the data, it can handle deep copies and does not get caught out by circular references.

Create a new mxml class in the project and call it AddressBookView.mxml and populate it with the source code from here. The mxml file contains some view related code, in this case we have a form, which is just a way of laying out some components, our form contains four text inputs and a button.

We also have a DataGrid, which is very similar to a JTable if you have ever coded Swing.

When the user inputs four lines of their address and click add, the click event is fired and the button has the handleAdd() function registered to handle click event for it. The handleAdd() function creates an empty AddressVO and populates it with the data from the text inputs in the form.

   private function handleAdd() : void
   {
      var address : AddressVO = new AddressVO();
      address.line1 = line1Input.text;
      address.line2 = line2Input.text;
      address.city = cityInput.text;
      address.postalCode = postalCodeInput.text;
		
      addressBookRO.addAddress(address);
   }

It then calls the method on the remote object (addAddress), this calls the addAddress(..) method on the java remote object, which adds the address to the address book and then sends back the contents of the address book as a List of AddressVOs. The remote object's result handler is pointing to the handleResult function, which updates our local copy of the list of addresses (we are using an ArrayCollection).

   private function handleResult( event : Object ) : void

   {

      addressList = event.result;

   }

The DataGrid mentioned earlier has a property of dataProvider set to reference the list of addresses, whenever that list changes, a 'binding event' is fired, which the DataGrid receives and re-populates itself.

<mx:DataGrid dataProvider="{addressList}" width="100%" height="100%" />

Flex allows you to break visual components down into sub-components so that you can manage your project source more easily, in addition as a java developer, you may want to take a look at the Cairngorm microarchitecture, which provides a set of patterns to allow you to better architect a project.

In the next guide, I will show you how to look at the output of the gateway to see how your object gets passed, I will also show you how you can debug your client-side flex code using the FlexBuilder debugger and show you how you can use JPDA to remote debug the java remote object. This will give you full end to end debugging.

Next is the code which allows us to hook onto the server and make our RPC call, this is declared inside the RemoteObject tag:

<mx:RemoteObject

   id="echoRO"

   destination="echoService"

   fault="handleFault(event)"

   result="handleResult(event)" />

<destination id="echoService">

   <properties>

   <source>fdsweb.EchoService</source>

   <scope>application</scope>

   </properties>

</destination>

Java to ActionScript
ActionScript to Java

On a real project, we would use the Cairngorm microarchitecture to abstract out our remote objects into a ServiceLocator, but as we are just wanting to play, lets just go with declaring the remote object in our mxml entry point file.

You will notice that the event handling code in the MXML file is written in action script and as such is declared in an mx:Script tag. The functions handleResult and handleFault are the same functions which we point our remote object event handlers to, handleClear describes what happens when the user clicks on the clear button (note the button has a click event handler which is pointing to this function) and finally handleSend describes what happens when the user clicks on the send button, apart from doing some trivial view stuff, this function calls the remote object:

echoRO.echo(message);

any method which is exposed on the remote java object can be called by the actionscript code (subject to security), as long as it passes a compatible parameter, see the docs for type mapping. The most important thing you will need to get your head around is that you do not assign the return of the remote method from the result of the call, in other words you do not assign it in the handleSend function. Remote object calls are asynchronous, so the client continues working in parallel to the server handling the method call, the result appears as an event on the remote object, which is handled as I mentioned earlier by the 'result' or 'fault' events on the remote object, which in our case point to handleResult and handleFault functions.

It is important to remember that the request and the response are asynchronous, so if you made request-A and then request-B you are likely to receive response-A and response-B, however, there is no guarantee and you could receive response-B and then response-A; see Asynchronous Call Token for a typical way of matching requests to responses if you need to.

As you are probably starting to work out, using the current techniques above, you would be limited to only using java parameters and return types which are mapped; fortunately however, Flex allows us to create complex objects which we can pass back and forth, often these objects are known as Data Transfer Objects or Value Objects, however, ultimately they are just objects.

In the next coffee-break guide, I will show how you can pass your own custom object to from flex to java and also a custom object from java to flex.

   <destination id="echoService">

      <properties>

         <source>fdsweb.EchoService</source>

         <scope>application</scope>

      </properties>

   </destination>

Inside the service tag. This allows the flex client to access the remote java class, you can read more about this in the docs, the above will work for you now.

Double check your class file has compiled and is under WEB-INF/classes.

Now you need to write a simple flex client to the java class, to save you time, I have done this, so create an empty Flex Application mxml file by doing: New>MXML Application and call it EchoView, leave the layout to its default.

You should have an mxml file now with an empty application tag inside it. Replace all of the contents of the file with this:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
	
   <!-- VIEW CODE -->
	
   <mx:Label text="Echo Service Simple RPC Example" fontSize="20" />	 
	    
   <mx:Spacer height="20" />
    
   <mx:TextInput id="messageInput" />
    
   <mx:HBox>
    			
      <mx:Button label="send" click="handleSend(messageInput.text);" />
      <mx:Button label="clear" click="handleClear();" visible="false" id="clear" />
		    	
   </mx:HBox>

   <mx:Label id="resultLabel" />

	

	

   <!-- REPRESENTS THE REMOTE OBJECT -->

   <mx:RemoteObject

      id="echoRO"

      destination="echoService"

      fault="handleFault(event)"

      result="handleResult(event)" />

	

	

      <!-- EVENT HANDLING CODE -->

      <mx:Script><![CDATA[

	

      import mx.controls.Alert;

			

      private function handleSend( message : String ) : void

      {

            resultLabel.text = "";

            echoRO.echo(message);

            clear.visible = true;

      }

	

      private function handleClear() : void

      {

            resultLabel.text = "";

            messageInput.text = "";

            clear.visible = false;

      }

	

      private function handleResult( event : Object ) : void

      {

            //resultLabel.text =  "" + event.result ;

            resultLabel.text =  event.result as String ;		

      }

	

      private function handleFault( event : Object ) : void

      {

            Alert.show( event.fault.faultCode + "\n" + event.fault.faultString, "fault" );

      }

			

      ]]>	</mx:Script>

	

</mx:Application>

Right click on EchoView.mxml and select run as > Flex Application

Your browser should then show our flex app with a text input and a button, give it a try by typing something in the text field and hitting send

In the next guide, I will give you a quick overview of the flex code which calls the java and handles the results.

Choose to create a Flex Data Services project and compile the application on the server

Change the root folder to be: [jboss root]/server/default/deploy/fdsweb.war

Point the root URL to where you expect the fdsweb.war web app to be, my app is at http://localhost:8080/fdsweb

I called the project FDSWeb, make sure you untick the 'use default location' and change it to point to the fdsweb.war file under deploy in jboss

Don't do anything with the build path yet, just create the project and switch to the Flex Perspective.

You should be presented with the file FDSWeb.mxml in the editor, just add a label in for us to read when we test our configuration:

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

make sure JBoss is running and then right click on the file in the navigator and select run as Flex Application.

Now I expect that you want to try and add some java into the project, but you will notice if you try and create a java source folder that Eclipse will not let you, so you need to add the following to your .project file:

Under build specs you need to add:

<buildCommand>

   <name>org.eclipse.jdt.core.javabuilder</name>

   <arguments>

   </arguments>

</buildCommand>

<nature>org.eclipse.jdt.core.javanature</nature>

Create a java source folder, for example src, create a package called fdsweb and a class called EchoService inside that package.

package fdsweb;


import java.text.DateFormat;

import java.text.SimpleDateFormat;

import java.util.Date;

public class EchoService

{



	public String echo( String inputMessage ) throws Exception

	{

		StringBuffer result = new StringBuffer();

		result.append("EchoService received ");

		result.append(inputMessage);

		result.append(" at ");

		result.append(dateFormat.format(new Date()));

		return result.toString();

	}

	private DateFormat dateFormat = new SimpleDateFormat("HH:mm:ss");



}

You will notice you get an error indicating that type java.lang.Object cannot be found (doesn't sound good ;-) ). However, this is just because you need to add the java libraries to your project.

project>properties>java build path>Libraries>add library>JRE System Library, also change your default output folder from bin to /FDSWeb/WEB-INF/classes in the project, click ok, etc.

Your java should now of compiled.

Ok, so we can now develop java and flex in the same project, at Adobe Consulting we do not tend to setup projects this way, we use the Web Tools plugin for Eclipse, plug into our source control repository, etc. However, this approach is good enough to allow you to start playing with flex and java integration. In the next post I will show how to integrate our flex code and our java code. Cold coffee again ? Maybe you should switch to frappaccinos !

[fds install]/resources/security/tomcat/flex-tomcat-common.jar
[fds install]/resources/security/tomcat/flex-tomcat-server.jar

into

[jboss root]/server/default/lib

Download the correct Xalan jars as described in "XPath Issues with JBoss 4.0.3 SP1", here http://www.adobe.com/support/documentation/en/flex/2/install.html#jboss

copy [fds install]/flex.war to a temporary directory and rename it fdsweb.war

insert into the WAR at fdsweb.war/WEB-INF/lib the Xalan jars. I have:

xalan.jar
xercesImpl.jar
xml-apis.jar

expand the war under the [jboss root]/server/default/deploy directory, calling the directory fdsweb.war

Start JBoss and go to: http://localhost:8080/fdsweb/

you should now see "Welcome to Adobe Flex Data Services 2! This is an empty .... "

In my next Coffee Break Guide, I will show you how to set up a very simple 'RPC' call between flex and java. Go drink your cold coffee !

JBoss Installation
JBoss XPath Issues
JBoss Download
Flex Data Services Download