Exadel Flamingo Developer Guide

Copy files"flamingo-service-1.8.1.jar", "amf-serializer-1.8.1.jar" (for AMF) and/or "hessian-3.1.3.jar"(for Hessian) into the "WEB-INF/lib" folder of your application. For EAR projects file "flamingo-service-1.8.1.jar" should be copied to the EAR root and specified in the "application.xml" file as a module.

If Seam Remoting is used in your project, you don't need any additional configuration and now can call the Seam components directly from Flex 2 using AMF and/or Hessian protocols.

<context-param>
    <param-name>flamingoConfig.webRemoteEnabled</param-name>
    <param-value>true</param-value>
</context-param>

If Seam Remoting is not used in your project:

This parameter shows that calls coming to URL "[server_name]/[context]/flamingo/amf/*" will be passed to the com.exadel.flamingo.service.seam.AMFToSeamServlet servlet.

Thus, using URL "/flamingo/amf/" you can call the servlet to access the Seam components via the AMF protocol.

This parameter shows that calls coming to URL "[server_name]/[context]/flamingo/hessian/*" will be passed to the com.exadel.flamingo.service.seam.HessianToSeamServlet servlet.

Thus, using URL "/flamingo/hessian/ " you can call the servlet to access the Seam components via the Hessian protocol.

<context-param>
    <param-name>flamingoConfig.webRemoteEnabled</param-name>
    <param-value>true</param-value>
</context-param>

where

"{server.name}:{server.port}" is server name:server port where your existing JBoss Seam application is running;

"helloworld" is the name of your existing application;

"helloAction" is the name of the component specified in the "HelloAction.java" file (see annotation @Name("helloAction") in 3.3.1);

"seam/resource/amf/" is the standard configuration while using Remoting. If you use another mapping for SeamResourceServlet or one of the Flamingo servlets, use the path specified in the "web.xml" file of your application for destination:

uri="http://{server.name}:{server.port}/helloworld/flamingo/amf"

Figure 3.1. HelloWorld.swf

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:word="*">
            
<hessian:HessianService xmlns:hessian="hessian.mxml.*"
id="service" destination="seam/resource/hessian/helloAction"/>
            
<mx:Panel title="Flamingo Hessian Hello World Sample"
paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
            
<mx:HBox>
   <mx:Label text='Whom do you want to say "Hello" to?'/>
            
   <mx:TextInput id="who"/>
            
   <mx:Button label="Say Hello" click="service.hello.send(who.text)"/>
</mx:HBox>
            
<mx:Label text='The server said: "{service.hello.lastResult}"'/>
            
</mx:Panel>
</mx:Application>

This sample shows how the hello method of server Seam component helloAction can be called using HessianService when clicking on the "Say Hello" button,

where

"helloAction" is the name of the component specified in the "HelloAction.java" file (see annotation @Name("helloAction") in 3.3.1);

"seam/resource/hessian/" is the standard configuration while using Remoting. Please note that the URL is relative, so the application will contact http://[origin server]/[application context]/[path to Seam/Flamingo servlet]/helloAction as a service. If you use another mapping for SeamResourceServlet or one of the Flamingo servlets, use the path specified in the "web.xml" file of your application in the URL pattern:

destination="flamingo/hessian/helloAction"

Figure 3.2. HelloWorld.swf

- classes

- lib

- src

package com.exadel.flamingo.javafx;
          
import javafx.stage.Stage;
import javafx.scene.Scene;
import javafx.scene.text.Text;
import javafx.scene.text.Font;
import javafx.scene.layout.HBox;
import javafx.scene.paint.Color;
import javafx.scene.text.TextOrigin;
import javafx.ext.swing.SwingButton;
import javafx.scene.layout.VBox;
import javafx.scene.control.TextBox;
          
import com.exadel.flamingo.javafx.samples.helloworld.javafx.HelloworldClient;
          
class Hello {
        public var name:String;
        public var str:String;
}
var helloModel = new Hello();
          
HelloworldClient.setServerUrl("http://localhost:8080/helloworld/seam/resource/hessian/helloAction");
          
          
var helloText: TextBox = TextBox {
       text: bind helloModel.name with inverse
       columns: 7
       selectOnFocus:true
}
          
var helloLabel = Text{
      y:8
      font: Font { name:"sansserif", size: 12 }
      fill: Color.BLACK
      content: bind "Server says: {helloModel.str}"
      textOrigin: TextOrigin.TOP
}
          
var helloButton = SwingButton  {
      text:"Say Hello!"
      action: function(){
             helloModel.str = HelloworldClient.CLIENT.hello(helloModel.name);
       }
}
          
Stage {
        title: "Helloworld Sample"
        width: 200
        height: 150
        scene: Scene {
                 content: VBox {
                         translateX: 5
                         translateY: 5
                         spacing: 10
                         content: [                
                                 HBox {
                                            content: helloText
                                            spacing: 10
                                 },
                                 HBox {
                                            content: helloButton
                                            spacing: 10
                             },
                                 HBox {
                                            content: helloLabel
                                            spacing: 10
                           }]
                 }
         }
}
        

This file creates a visual form to send data from the client side to the server,

where

"helloAction" is the name of the component specified in the "HelloAction.java" file created for the Seam application (see annotation @Name("helloAction") in 3.3.1);

"http://localhost:8080/helloworld/seam/resource/hessian/" is the standard configuration while using Remoting. Please note that the URL is relative, so the application will contact http://[origin server]/[application context]/[path to Seam/Flamingo servlet]/helloAction as a service. If you use another mapping for SeamResourceServlet or one of the Flamingo servlets, use the path specified in the "web.xml" file of your application in the URL pattern:

destination="flamingo/hessian/helloAction"

package com.exadel.flamingo.javafx.samples;
public interface IHelloAction {
    public String hello(String name);
}

package com.exadel.flamingo.javafx.samples.javafx;
import com.caucho.hessian.client.HessianProxyFactory;
import com.exadel.flamingo.javafx.samples.IHelloAction;
import java.net.MalformedURLException;
public class HelloworldClient {
    public static HelloworldClient CLIENT;
    
    private String _url;
    private HelloworldClient(String string) {
        _url = string;
    }
    private IHelloAction _service;
    public static void setServerUrl(String url) {
        CLIENT = new HelloworldClient(url);
    }
    private IHelloAction getService() {
        if (_service == null) {
            try {
                HessianProxyFactory factory = new HessianProxyFactory();
                _service = (IHelloAction) factory.create(IHelloAction.class, _url);
            } catch (MalformedURLException ex) {
                System.out.println(ex);
            }
        }
        return _service;
    }
    public String hello(String s) {
        return getService().hello(s);
    }
}

This sample shows how the HelloworldClient class creates a connection with the server with the help of the HessianProxyFactory class and calls the corresponding methods of the component on the server.

Here is an example of usage of the JavaFX interpretator:

Figure 3.3. HelloWorld

This parameter shows that calls coming to URL "[server_name]/[context]/flamingo/amf/*" will be passed to the com.exadel.flamingo.service.spring.AMFToSpringServlet servlet.

Thus, using URL "/flamingo/amf/" you can call the servlet to access the Spring beans via the AMF protocol.

This parameter shows that calls coming to URL "[server_name]/[context]/flamingo/hessian/*" will be passed to the com.exadel.flamingo.service.spring.HessianToSpringServlet servlet.

Thus, using URL "/flamingo/hessian/ " you can call the servlet to access the Seam components via the Hessian protocol.

where

"{server.name}:{server.port}" is server name:server port where your existing JBoss Seam application is running;

"helloworld" is the name of your existing application;

"helloService" is the name of the bean specified in the application context file or via annotation like @Component(“helloService”) added to the HelloService class;

"flamingo/amf/" is the standard configuration while using servlets. If you use another mapping for HessianToSpringServlet, use the path specified in the "web.xml" file of your application for destination.

Figure 3.4. HelloWorld.swf

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:word="*">
          
<hessian:HessianService xmlns:hessian="hessian.mxml.*"
id="service" destination="flamingo/hessian/helloService"/>
          
<mx:Panel title="Flamingo Spring Hessian Hello World Sample"
paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
          
<mx:HBox>
   <mx:Label text='Whom do you want to say "Hello" to?'/>
          
   <mx:TextInput id="who"/>
          
   <mx:Button label="Say Hello" click="service.hello.send(who.text)"/>
</mx:HBox>
          
<mx:Label text='The server said: "{service.hello.lastResult}"'/>
          
</mx:Panel>
</mx:Application>

This sample shows how the hello method of server Spring service bean helloService can be called using "HessianService" when clicking on the "Say Hello" button,

where

"helloService" is the name of the component specified in the application context file;

"flamingo/hessian/" is the standard servlet configuration. Please note that the URL is relative, so the application will contact http://[origin server]/[application context]/[path to Spring/Flamingo servlet]/helloService as a service. If you use another mapping for HessianToSpringServlet use the path specified in the "web.xml" file of your application in the URL pattern.

Figure 3.5. HelloWorld.swf

For the entities like these ones:

@Entity
public class Person implements Serializable {
    private Long id;
    private Integer version;
    private String name;
    private Set<Book> books;
    @OneToMany(mappedBy = "person", cascade = CascadeType.ALL, fetch = FetchType.EAGER)
    public Set<Book> getBooks() {
        return books;
    }
    public void setBooks(Set<Book> books) {
        this.books = books;
    }
    @Id
    @GeneratedValue
    public Long getId() {
        return id;
    }
    public void setId(Long id) {
        this.id = id;
    }
    @Version
    public Integer getVersion() {
        return version;
    }
    public void setVersion(Integer version) {
        this.version = version;
    }
    @Length(max = 20)
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
}

@Entity
public class Book implements Serializable {
    private Long id;
    private String name;
    protected Person person;
    @ManyToOne(optional=false, cascade=CascadeType.ALL, fetch=FetchType.EAGER)
    @NotNull
    public Person getPerson() {
        return person;
    }
    public void setPerson(Person person) {
        this.person = person;
    }
    @Id
    @GeneratedValue
    public Long getId() {
        return id;
    }
    public void setId(Long id) {
        this.id = id;
    }
    @Length(max = 20)
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
}

you will have the following application after screens generation:

Figure 4.13. Person List Screen

Figure 4.14. Person Form Screen

Figure 4.15. Book Form Screen

This component uses the AMF protocol. It replaces the former SeamValidator starting from deprecated version 1.0.2.

<context:component-scan base-package="com.exadel.flamingo.service"/>

package com.mycompany.myproject;
import org.hibernate.validator.Length;
import org.jboss.seam.annotations.Name;
import javax.persistence.Entity;
@Name("person")
@Entity(name="Person")
public class PersonBean {
    private String lastName; 
    @Length(min=3, max=40)
    public String getLastName() {
        return lastName;
    }
}

<flamingo:EntityValidator id="validator"
  destination="person"
  source="{valueId}"
  validationTarget="lastName"
  property="text" />
<mx:Form>
    <mx:TextInput id="valueId" />
    <mx:Button label="Validate" click="validator.validate()" />
</mx:Form>

HessianEntityValidator has the same properties and methods as EntityValidator. It replaces the former SeamValidator starting from deprecated version 1.0.2. See the code sample for this component below.

<flamingo:HessianEntityValidator id="validator" 
  destination="seam/resource/hessian/person" 
  validationTarget="lastName" 
  source="{test}" 
  property="text" />
<mx:Form>
    <mx:TextInput id="test" />
    <mx:Button label="Validate" click="validator.validate()" />
</mx:Form>

This component uses the AMF protocol.

<context:component-scan base-package="com.exadel.flamingo.service"/>

<mx:Script>
    <![CDATA[
        private function loginResultHandler(event:ResultEvent):void
        {
            var results:Array = event.result as Array;
            if (results[3])
            {
                Alert.show('Successfully logged in');
            } else {
                Alert.show('Login failure');
            }
        }
    ]]>
</mx:Script>
        
<flamingo:CallSet id="loginCallSet" 
  result="loginTestResultHandler(event)"
  destination="callSet">
    <flamingo:Call component="identity" method="setUsername"/>
    <flamingo:Call component="identity" method="setPassword"/>
    <flamingo:Call component="identity" method="login"/>
    <flamingo:Call component="identity" method="isLoggedIn"/>
</flamingo:CallSet>
        
<mx:Button id="loginBtn" label="Login" click="loginCallSet.send(["flamingo"],["secret"],[],[])"/>

<services-config>
    <services>
        <service
            id="binding-service"
            class="flex.messaging.services.RemotingService"
            messageTypes="flex.messaging.messages.RemotingMessage">
            <destination id="callSet"/>
            <default-channels>
                <channel ref="seam-amf"/>
            </default-channels>
        </service>
    </services>
    <channels>
        <channel-definition id="seam-amf" class="mx.messaging.channels.AMFChannel">
            <endpoint
                uri="http://{server.name}:{server.port}/myapp/seam/resource/amf/"
                class="flex.messaging.endpoints.AMFEndpoint"/>
        </channel-definition>
    </channels>
</services-config>

<component name="com.exadel.flamingo.service.callset.callSetManager" class="com.exadel.flamingo.flex.callset.EJBCallSetManager"/>

HessianCallSet has the same properties, events and methods as CallSet. See the code sample for this component below.

<flamingo:HessianCallSet id="loginCallSet" 
  destination="seam/resource/hessian/"
  result="loginTestResultHandler(event)">
    <flamingo:SeamHessianCall component="identity" method="setUsername"/>
    <flamingo:SeamHessianCall component="identity" method="setPassword"/>
    <flamingo:SeamHessianCall component="identity" method="login"/>
    <flamingo:SeamHessianCall component="identity" method="isLoggedIn"/>
</flamingo:HessianCallSet>

This component uses the AMF protocol.

If you use BindingService to bind an object that is an entity (has the javax.persistence.Entity annotation) there is a possiblity for you in Flamingo to automatically merge the content of the object into the database when committing it to the server.

For Seam, you need to have the managed persistence context (JPA) correctly configured and have option "flamingoConfig.bindingManagerPersistsEntity true" specified in the "seam.properties" file.

For Spring, you need to have Hibernate SessionFactory correctly configured and file "flamingoConfiguration.properties" with content bindingManager.persistEntities=true defined in classpath.

Add the following string to Spring configuration:

<util:properties id="flamingoConfiguration" location="classpath:flamingoConfiguration.properties"/>

<context:component-scan base-package="com.exadel.flamingo.service"/>

package com.mycompany.myproject.seam;
import org.jboss.seam.ScopeType;
import org.jboss.seam.annotations.Name;
import org.jboss.seam.annotations.Scope;
@Name("personBean")
@Scope(ScopeType.SESSION)
public PersonBean{
    private String firstName;
    private String lastName;
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
}

package com.mycompany.myproject.flex.vo
{
[RemoteClass(alias="com.mycompany.myproject.seam.PersonBean")] 
[Bindable]
public class PersonVO
{
private var _firstName:String;
private var _lastName:String;
public function get firstName():String
{
return _firstName;
}
public function set firstName(value:String):void
{
_firstName = value;
}
public function get lastName():String
{
return _lastName;
}
public function set lastName(value:String):void
{
_lastName = value;
}
}
}

<mx:Application creationComplete="init()">
<mx:Script>
<![CDATA[
import com.mycompany.myproject.flex.vo.PersonVO;
import mx.controls.TextInput;
[Bindable]
private var user:PersonVO;
private function init():void 
{
user = new PersonVO();
user.firstName = "John";
user.lastName = "Smith";
}
]]>
</mx:Script>
       
<flamingo:BindingService id="personBinding" 
    destination="personBean" 
    source="{user}" />
       
<mx:TextInput text="{user.firstName}"/>
<mx:TextInput text="{user.lastName}"/>
<mx:Button label="Send data to server" click="personBinding.commit()"/>
<mx:Button label="Get data from server" click="personBinding.update()"/>
</mx:Application/>

<component name="com.exadel.flamingo.flex.binding.bindingManager"  class="com.exadel.flamingo.flex.binding.EJBBindingManager"/>

HessianBindingService has the same properties, events and methods as BindingService. See the code sample for this component below.

<flamingo:HessianBindingService id="personBinding" 
destination="seam/resource/hessian/personBean" 
source="{user}" />

Here is an example of usage of several SeamRemoteObject components in the context of one conversation:

"ConversationStarter.java":

@Name("conversationStarter")
public class ConversationStarter {
    @Begin
    public void start() {
    }
}

"ConversationStopper.java":

@Name("conversationStopper")
public class ConversationStopper {
    @End()
    public void stop() {
    }
}

<flamingo:SeamRemoteObject id="starter" destination="conversationStarter"/>
<flamingo:SeamRemoteObject id="stopper" destination="conversationStopper"/>
<mx:Form>
    <mx:FormItem>
<mx:Button label="Start conversation" click="starter.start();" />
<mx:Button label="Stop conversation" click="stopper.stop();" />
    </mx:FormItem>
</mx:Form>

When clicking on the "Start" button the conversation starts on the server, when "Stop" - the conversation is stopped. You can check this by clicking on the "Start" button twice: you will get an error message that the conversation is running already.

Here the events and methods used by SeamRemoteObject are described.

The SeamRemoteObject component includes the following events:

The SeamRemoteObject component has the following methods:

This component uses the Hessian protocol.

<context:component-scan base-package="com.exadel.flamingo.service"/>

package com.exadel.flamingo.javafx;
import javafx.stage.Stage;
import javafx.scene.Scene;
import javafx.scene.text.Text;
import javafx.scene.text.Font;
import javafx.scene.layout.HBox;
import javafx.scene.paint.Color;
import javafx.scene.text.TextOrigin;
import javafx.ext.swing.SwingButton;
import javafx.scene.layout.VBox;
import javafx.scene.control.TextBox;
            
import com.exadel.flamingo.javafx.components;
            
var validator = HessianEntityValidator {
          destination: "person" 
          property: "lastName"
}
            
var textField: TextBox = TextBox {
      text: "test"
      columns: 7
      selectOnFocus:true
}
            
var sampleLabel = Text{
      y: 8
      font: Font { name:"sansserif", size: 12 }
      fill: Color.BLACK
      content: bind validator.returnedMessage
      textOrigin: TextOrigin.TOP
}
            
var validateButton = SwingButton  {
       text: "Validate"
       action: function(){
              validator.validate();
        }
}
            
Stage {
            width: 300
            height: 200
            title: "Validation Sample"
            scene: Scene {
                content: VBox {
                        translateX: 5
                        translateY: 5
                        spacing: 10
                        content: [                
                                HBox {
                                          content: sampleLabel
                                          spacing: 10
                                 },
                                 HBox {
                                                           content: textField
                                            spacing: 10
                                 },
                                 HBox {
                                                           content: validateButton
                                             spacing: 10
                                 }]
                        }
            }
}
            
          

Add files "ConversationStarter.java" and "ConversationStopper.java"on the server:

"ConversationStarter.java":

@Name("conversationStarter")
public class ConversationStarter {
    @Begin
    public void start() {
    }
}

"ConversationStopper.java":

@Name("conversationStopper")
public class ConversationStopper {
    @End()
    public void stop() {
    }
}

This is an example of the application that works with conversations:

package com.exadel.flamingo.javafx;
      
import javafx.stage.Stage;
import javafx.scene.Scene;
import javafx.scene.layout.HBox;
import javafx.ext.swing.SwingButton;
import javafx.scene.layout.VBox;
      
import com.exadel.flamingo.javafx.seam.SeamServiceFactory;
      
SeamServiceFactory.setUrl("http://localhost:8080/helloworld/seam/resource/hessian");
      
var buttonStart = SwingButton  {
      text: "Start conversation"
      action: function(){
             SeamServiceFactory.getService(ConversationStarter.class,
                                    "conversationStarter").start();
      }
}
      
var buttonStop = SwingButton  {
      text: "Stop conversation"
      action: function(){
            SeamServiceFactory.getService(ConversationStopper.class,
                                   "conversationStopper").stop();
      }
}
      
Stage {
           width: 300
           height: 200
           title: "Validation Sample"
           scene: Scene {
               content: VBox {
                       translateX: 5
                       translateY: 5
                       spacing: 10
                       content: [                
                               HBox {
                                         content: buttonStart
                                         spacing: 10
                               },
                               HBox {
                                                        content: buttonStop
                                         spacing: 10
                                     }]
                       }
           }
}
      

When clicking on the "Start" button the conversation starts on the server, when "Stop" - the conversation is stopped. You can check this by clicking on the "Start" button twice: you will get an error message that the conversation is running already.

When you use Basic authentication to secure access to destinations in Flex, you usually secure the endpoints of the channels that these destinations use in the "web.xml" file. You then configure the destination to access the secured resource in order to be challenged for a user name (principal) and password (credentials). The web browser performs the challenge, which happens independently of Flex. The web application container authenticates the user's credentials.

With Flamingo you don't need to configure secure channels for basic authentication. If you have basic authentication applied on the server either via standard Java EE configuration in the "web.xml" file or via native Spring Security or Seam configuration, you don't need any additional settings in Flex.

<web:authentication-filter>

<security-constraint>

<web:authentication-filter url-pattern="/seam/resource/*" auth-type="basic"/> 

<http auto-config="true">
      <intercept-url pattern="/flamingo/**" access="ROLE_USER" />
      <intercept-url pattern="/**" filters="none" />
    </http>
    <authentication-provider>
      <password-encoder hash="md5"/>
        <user-service>
          <user name="rod" password="a564de63c2d0da68cf47586ee05984d7" authorities="ROLE_USER" />
          <user name="dianne" password="65d15fe9156f9c4bbffd98085992a44e" authorities="ROLE_USER" />                         
        </user-service>
   </authentication-provider>

When using custom authentication you should call certain methods on the server to perform the authentication itself. For custom authentication, Flex uses a custom login adapter, known as a login command, to check a user's credentials and log a principal into the application server. If you also want to use custom authorization, you must link the specified role references to roles that are defined in your application server's user store. Flamingo does not require you to configure roles for custom authentication/authorization as all necessary data is taken from the server configuration.

Seam

The standard approach to usage of custom authentication is the use of the identity component as shown in example 5.2.1.3 with the help of the CallSet component. After that, user will be logged on the server. As an alternative to this, you can use the setCredentials() method for the RemoteObject class (HessianService does not support this mechanism):

<mx:RemoteObject id="service" destination="identity"/>
<mx:Button label="Authenticate" click="service.setCredentials('username', 'password'); service.isLoggedIn()"/>

Spring

There are two ways how you can use custom authentication for Spring:

1. Create a Spring Service bean with methods like "login", "doLogout", "isLoggedIn" that will be requested from Flex. This bean will perform authentication using Spring Security API.

2. Use methods "setCredentials", "logout" of the RemoteObject component. For example:

<mx:RemoteObject id="service" destination="myService"/>
<mx:Button label="Call secure method" click="service.setCredentials('username', 'password'); service.callMethod()"/>

In this example, before calling method callMethod the authentication will be performed on the server according to Spring Security configuration set in the application.

Method "logout" of RemoteObject will remove currently authenticated principal from the security context. Methods "setCredentials" and "logout" affect not only the destination they were called from but the whole application as well.

In this mode you can check which roles a user currently logged on has and then deny or grant access to some resource. The roles are usually defined on the server side in the method described in the "components.xml" file:

<security:identity authenticate-method="#{authenticator.authenticate}"/>

After calling identity.login() you can check a role using the identity.hasRole() server call.

Checking Seam permission involves executing the rule engine, therefore it should be done on server. Typically you need to check permissions in the way described below:

<mx:Script>
    <![CDATA[
    private function permissionResultHandler(event:ResultEvent):void
    {
        if ( event.result ) {
            Alert.show("You have permission");
        } else {
            Alert.show("You do not have permission");
        }
    }
    ]]>
</mx:Script>
<mx:RemoteObject id="identityService" destination="identity">
    <mx:method name="hasPermission" result="permissionResultHandler(event)" />
</mx:RemoteObject>
<mx:Button label="Check permission" click="identityService.hasPermission('account',  'delete', null)"/>