Chapter 4. Creating New Flamingo Project

You can create a new Flamingo project in two ways: using Adobe Flex Builder or Maven FlamingoApp Generator Plugin.

4.1. Create New Flamingo Project Using Flex Builder

Flamingo supports the following versions of Adobe Flex Builder: Adobe® Flex™ Builder™ 2.0.1 HotFix 2 and higher.

Follow the instructions how to create a new sample project with the help of Adobe Flex Builder below. This sample application will use Flamingo EntityValidator component to validate text entered by user against Hibernate Validator annotations specified in the entity declaration (see more information and code samples in the Flamingo Components Chapter: EntityValidator):

  • Run Adobe Flex Builder. Create a new Project: File > New > Flex Project:

Create New Project

Figure 4.1. Create New Project


  • Select Project Type: select "Basic (e.g. XML or web service from PHP/JSP/ASP.NET )". Click Next.

Select Project Type

Figure 4.2. Select Project Type


  • Specify a name for your project: e.g. "validation". Browse a destination folder where your project will be located. Click Next.

Project Name and Location

Figure 4.3. Project Name and Location


  • Set the build paths for the new Flex project: Library path > Add SWC:

Add SWC

Figure 4.4. Add SWC


  • Browse the "flamingo-flex-2.1.swc" file and click OK:

Browse SWC

Figure 4.5. Browse SWC


  • The .swc file is now added. Fields "Main Application File" and "Output Folder" are predefined by the system. Click on Finish.

Finish Project Creation

Figure 4.6. Finish Project Creation


Your new Flex Project is now created!

  

To have this project working you need a running Seam or Spring web application with integrated Flamingo via URL "http://localhost:8080/validation/" with the entity named Person; see example in chapter 5.1.1.1.3 Code Sample. You can use the corresponding "validation" example in the Flamingo download bundle.

  

Please add implementation according to the protocol you use: AMF or Hessian.

4.1.1. AMF

  • Enter the following content into file "validation.mxml" that uses the EntityValidator component to validate the lastName property, entered in the first editbox, for the Person entity specified as destination property in EntityValidator:

    
    <?xml version="1.0" encoding="utf-8"?>
    <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
        xmlns:flamingo="com.exadel.flamingo.flex.components.flamingo.*">
        
        <flamingo:EntityValidator id="validator" 
            destination="Person" 
            validationTarget="{target.text}" 
            source="{test}" 
            property="text" 
            required="false"/>
            
        <mx:Form width="100%" >
            <mx:FormItem label="Validation target:" width="100%" >
                <mx:TextInput id="target" width="100%" text="lastName" />
            </mx:FormItem>
            <mx:FormItem label="Input value:" width="100%" >
                <mx:TextInput id="test" width="100%" />
            </mx:FormItem>
            <mx:FormItem>
                <mx:Button label="Validate" click="validator.validate()" />
            </mx:FormItem>
        </mx:Form>
        
    </mx:Application>
  • Create file "services-config.xml" with the following content to configure destination that EntityValidator component uses:

    
    <?xml version="1.0" encoding="UTF-8"?>

    <services-config>
        <services>
            <service
                id="validate-service"
                class="flex.messaging.services.RemotingService"
                messageTypes="flex.messaging.messages.RemotingMessage">
                <destination id="Person"/>
                <default-channels>
                    <channel ref="default-amf"/>
                </default-channels>
            </service>      
        </services>

        <channels>
            <channel-definition id="default-amf" class="mx.messaging.channels.AMFChannel">
                <endpoint
                    uri="http://localhost:8080/validation/seam/resource/amf"
                    class="flex.messaging.endpoints.AMFEndpoint"/>
            </channel-definition>  
        </channels>

    </services-config>

Note

For Spring change uri in the channel definition to http://localhost:8080/validation/flamingo/amf.

  • Configure the project: click on the "validation.mxml" file > Properties > Flex compiler.

Configuration

Figure 4.7. Configuration


  • Enter additional compiler arguments: "-services "services-config.xml"" to take into consideration the settings of destination set in the "services-config.xml" file:

Flex Compiler

Figure 4.8. Flex Compiler


  • Click on the Run button to run the project:

Run the Project

Figure 4.9. Run the Project


  • Type in your browser the url to the .swf file: "http://localhost:8080/validation/validation.swf"

  • Enjoy the results!

Validation.swf

Figure 4.10. Validation.swf


4.1.2. Hessian

  • Create file "validation.mxml" with the following content to use component HessianEntityValidator to validate the lastName property for the person entity:


<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:flamingo="com.exadel.flamingo.flex.components.flamingo.*">
    
    <flamingo:HessianEntityValidator id="validator" 
        destination="{destination.text}" 
        validationTarget="{target.text}" 
        source="{test}" 
        property="text" 
        required="false"/>
        
    <mx:Form width="100%" >
        <mx:FormItem label="Destination:" width="100%" >
            <mx:TextInput id="destination" width="100%"  text="http://localhost:8080/validation/seam/resource/hessian/Person" />
        </mx:FormItem>
        <mx:FormItem label="Validation target:" width="100%" >
            <mx:TextInput id="target" width="100%" text="lastName" />
        </mx:FormItem>
        <mx:FormItem label="Input value:" width="100%" >
            <mx:TextInput id="test" width="100%" />
        </mx:FormItem>
        <mx:FormItem>
            <mx:Button label="Validate" click="validator.validate()" />
        </mx:FormItem>
    </mx:Form>
    
</mx:Application>    
    

Note

For Spring change the value of text in TextInput with id="destination" to "http://localhost:8080/validation/flamingo/hessian/Person".

  • Click on the Run button to run the project:

Run the Project

Figure 4.11. Run the Project


  • Type in your browser the url to the .swf file: "http://localhost:8080/validation/validation.swf"

  • Enjoy the results!

Validation.swf

Figure 4.12. Validation.swf


4.2. Create New Flamingo Project Using Flamingo Generator Commands

To run Maven Flamingo Generator Commands you need to have Maven 2 installed. Make sure you have started the "flamingoinstall" shell script as described in Chapter 3: Section 3.1, “Downloading and Installing Flamingo 2.1”.

Flamingo provides you with the following commands to generate a project or some of its parts:

  • flamingo create project

  • flamingo create entity

  • flamingo create screen

  • flamingo generate beans

  • flamingo help

There is a "templates" folder inside "bin" that contains templates written on Groovy for commands create screen, create entity, generate beans used for files generation. You can modify these templates according to your needs and then run generation. For example, it may be useful to apply own design of generated Flex screens or implement necessary copyright header for all generated files of the project, etc.

Tip

If you want to see a detailed log of the generation process add "-v" to the command used, this option turns the verbose mode on, e.g.: flamingo create entity -v

4.2.1. Create a Project

  • Run Command Line and enter the "flamingo create project" command from any folder you are in;

  • Select the necessary application type when question "Please choose the type of application to generate (flamingo-seam, flamingo-spring)[flamingo-seam]" appears (options mentioned in the square brackets are the default ones taken from the "FlamingoSDK.properties" file, they will be used when you simply press the Enter button);

  • Then answer the questions appearing according to the previous choice :

Table 4.1. Seam Configuration

QuestionAnswer Description
Please enter the location in which your new application will be created (i.e. c:/java/development): Specify path to the location where the folder with the project will be created.
Enter the project name (e.g. myproject): [myproject] Project name will be used when creating a target file: .war or .ear.
Please enter the root package name for your project (e.g. com.mydomain.myproject): [com.sample] The name specified will be used as a package name for the source files.
Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support)? (ear, war): [ear] Select whether you want to create an Enterprise Archive file (EAR) and use EJB support or a simple Web Archive file (WAR). If you select WAR, the database sample code will not be suggested to be created.
Will this project have Flex or JavaFX user interface? (flex, javafx): [flex]Select a required technology for the client side.
Will this project use Hessian or AMF protocol? (amf, hessian): [amf]This question will appear only if Flex is selected for the required interface. According to a user's choice, a dependency will be configured: "amf-serializer-2.1.jar" or "hessian-3.1.3.jar", and the client source files will be generated.
Will this project use Seam Remoting or Flamingo servlets? (servlets, remoting, both): [servlets] If you select Seam Remoting, the SeamResource servlet will be configured with a standard path in the "web.xml" file. If you select Flamingo servlet, either AMF Remote servlet or Hessian Remote servlet (depends on your previous answer) will be configured in the "web.xml" file.
What kind of database are you using? (hsql, mysql, oracle, postgres, mssql, db2, sybase, none): [hsql] This one and all further questions will appear only if you selected EAR deployment for your project. If one of the database types is selected, the corresponding Hibernate dialect and JDBC driver are automatically defined for it. If "none" is specified, the wizard will stop and no sample database code will be generated.
Enter the JDBC URL for your database (e.g. jdbc:hsqldb:.): [jdbc:hsqldb:.]Please configure JDBC URL for your existing database. If you use not a "hsql" database, copy the "jar" file with the jdbc driver into the folder included into the server classpath application, e.g.: for JBoss - "jboss/server/default/lib".
Enter database username: [sa]Specify the username to perform connection to the database.
Enter database password: []Specify the password to perform connection to the database. Type "NOPASSWORD" to reset the value to an empty password. If the Enter button is clicked the system will use the password value specified for the previous project.
Do you want to update the database schema each time you deploy? (y, n): [y]If yes, Hibernate will update the database schema each time when your project is deployed. If no, only validation of the database schema and entity model will be performed.
Enter the entity class name (Flex source files to view and modify entities will be generated as well): [Person] Specify the entity class name to generate sample source code to view and edit entities of this class. Sample code will be generated on the server and client side.

 

Table 4.2. Spring Configuration

QuestionAnswer Description
Please enter the location in which your new application will be created (i.e. c:/java/development): Specify path to the location where the folder with the project will be created.
Enter the project name (e.g. myproject): [myproject] Project name will be used when creating a target file: .war or .ear.
Please enter the root package name for your project (e.g. com.mydomain.myproject): [com.sample] The name specified will be used as a package name for the source files.
Will this project have Flex or JavaFX user interface? (flex, javafx): [flex]This question will appear only if Flex is selected for the required interface. Select a required technology for the client side.
Will this project use Hessian or AMF protocol? (amf, hessian): [amf]According to a user's choice, a dependency will be configured: "amf-serializer-2.1.jar" or "hessian-3.1.3.jar", and the client source files will be generated.
What kind of database are you using? (hsql, mysql, oracle, postgres, mssql, db2, sybase, none): [hsql] If one of the database types is selected, the corresponding Hibernate dialect and JDBC driver are automatically defined for it. If "none" is specified, the wizard will stop and no sample database code will be generated.
Enter the JDBC URL for your database (e.g. jdbc:hsqldb:.): [jdbc:hsqldb:.]Please configure JDBC URL for your existing database. If you use not a "hsql" database, copy the "jar" file with the jdbc driver into the folder included into the server classpath application, e.g.: for JBoss - "jboss/server/default/lib".
Enter database username: [sa]Specify the username to perform connection to the database.
Enter database password: []Specify the password to perform connection to the database. Type "NOPASSWORD" to reset the value to an empty password. If the Enter button is clicked the system will use the password value specified for the previous project.
Do you want to update the database schema each time you deploy? (y, n): [y]If yes, Hibernate will update the database schema each time when your project is deployed. If no, only validation of the database schema and entity model will be performed.
Enter the entity class name (Flex source files to view and modify entities will be generated as well): [Person] Specify the entity class name to generate sample source code to view and edit entities of this class. Sample code will be generated on the server and client side.

If you've done everything correctly so far you will see a project template created in the folder you specified. The template project structure varies depending on the settings you defines during project generation. Please have a look at Seam+JavaFX project structure.


...
\---Project Name
    |   build.txt
    |   flamingoproject.properties
    |   pom.xml
    |   readme.txt
    |
    +---java
    |   |   pom.xml
    |   |
    |   \---src
    |       \---main
    |           \---java
    |               \---com
    |                   \---exadel
    |                       \---docs
    |                           \---javafx
    |                                   ILoginAction.java
    |                                   LoginClient.java
    |                                   ServiceFactory.java
    |
    +---javafx
    |   |   javafx-build.xml
    |   |   pom.xml
    |   |
    |   \---src
    |       \---main
    |           \---javafx
    |               \---com
    |                   \---exadel
    |                       \---docs
    |                           \---javafx
    |                               |   FXClient.fx
    |                               |   Helper.fx
    |                               |   LoginForm.fx
    |                               |
    |                               \---table
    |                                       Table.fx
    |
    \---web
        |   build.xml
        |   pom.xml
        |   security.properties
        |
        \---src
            \---main
                +---java
                |   \---com
                |       \---exadel
                |           \---docs
                |               \---service
                |                       AuthenticatorAction.java
                |
                +---resources
                |       seam.properties
                |
                \---webapp
                    |   hello.jsp
                    |   index.html
                    |
                    +---jnlp
                    |       Flamingo Demo.jnlp
                    |
                    \---WEB-INF
                            components.xml
                            jboss-web.xml
                            web.xml
        

However, you need to take a few steps before building the project you've just created.

  • Navigate to the web folder

  • Run

    
    
     $ant -f build.xml create-keyEntry
     

    Note:

    Please note that in order to execute the command you need to have Apache Ant installed on your local machine. The latest version of this software can be downloaded at the official web site.

    This command generates a certificate which validity period is 90 days. If you want to change it, you will need to edit the validity attribute in the "web/build.xml" file.

    Note:

    * You only need to perform these steps once. Once done, you can build the project the usual way by executing standard Maven goals: compile, package, install, etc.

    * In case if you acquire a real certificate from a certificate authority (CA): a. You will not need to execute step 2. b. You will need to adjust properties in the file "web/security.properties" to reflect your keystore configuration.

4.2.2. Create Entity

In order to create an entity follow these steps:

  • Go to the root folder of the generated project: (e.g. c:/java/development/myproject);

  • Run Command Line and enter the "flamingo create entity" command;

  • Enter a new entity name.

Table 4.3. Create Entity

QuestionAnswer Description
Please enter entity class nameEnter a name for the entity class, e.g.: Book
Would you like to create JUnit test for a new entity? (yes, no) [yes]This option allows user to create a JUnit test with all necessary service classes for different entities depended on Seam/Spring kind of the project.

Tip

For new projects no default values will be offered. Type an option suggested in brackets or specify the defaults manually in the "flamingoproject.properties" file.

4.2.3. Create Screen

Command create screen is used to generate .mxml source files of CRUD (create, read, update, delete) screens for existing entities. In order to create a screen follow these steps:

  • Go to the root folder of the generated project: (e.g. c:/java/development/myproject);

  • Run Command Line and enter the "flamingo create screen" command;

In the result a screen with a form to edit entity and a screen listing entities of application data saved in the database will be generated. See a sample below.

During the create screen operation ActionScript files are generated automatically, so there is no need in additional running of the generate beans command.

Tip

For new projects no default values will be offered. Type an option suggested in brackets or specify the defaults manually in the "flamingoproject.properties" file.

4.2.3.1. Flamingo Create Screen Example

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:

Person List Screen

Figure 4.13. Person List Screen


Person Form Screen

Figure 4.14. Person Form Screen


Book Form Screen

Figure 4.15. Book Form Screen


4.2.4. Generate ActionScript Files from Java Files

Command flamingo generate beans generates AS files for java classes. In order to generate the files follow these steps:

  • Go to the root folder of the generated project: (e.g. c:/java/development/myproject);

  • Run Command Line and enter the "flamingo generate beans" command;

  • The system automatically determines whether you have Seam or Spring project. Answer the following questions for a Spring/Flex project:

Table 4.4. Generate Beans for Spring/Flex project

QuestionAnswer Description
Enter the related path to the .java files (starts with web/src/main/java/) [root_package_name]root_package_name is the package name for the source files specified when creating a project (e.g. com.sample).
Enter the name of existed entity file to generate .as files [all][all] generates .as files for all entities in the specified folder.

  • If some beans had already been created before the system will propose you to override them, you will be able to override them one by one, all beans at once or not to override them at all.

  • The following questions will appear for a Seam/Flex project:

Table 4.5. Generate Beans for Seam/Flex project

QuestionAnswer Description
Enter the related path to the .java files (starts with ejb/src/main/java/) [root_package_name]root_package_name is the package name for the source files specified when creating a project (e.g. com.sample).
Enter the name of existed entity file to generate .as files [all]Enter a name for the existing entity file to generate the files, e.g.: if you enter Person the flex/src/main/flex/com/sample/vo/Person.as bean will be generated for entity ejb/src/main/java/com/sample/Person.java entity.

Tip

For new projects no default values will be offered. Type an option suggested in brackets or specify the defaults manually in the "flamingoproject.properties" file.