Building your client-side application

Reference : http://livedocs.adobe.com/blazeds/1/blazeds_devguide/build_apps_4.html#170990

You write the client-side part of a BlazeDS application in Flex, and then use Flex Builder or the mxmlc command line compiler to compile it.

Note: This content assumes you have a BlazeDS Turnkey installation. That installation includes all the files necessary to complete these instructions.

Before you begin

Before you begin to develop your client-side code, determine the files required to perform the compilation. Ensure that you configured your Flex installation to compile SWF files for BlazeDS applications.

Note: When you compile an application using mxmlc, by default the compiler references the flex-config.xml configuration file, which specifies to include the libs/player directory in the library path for Flash Player. When you compile an application for AIR, use the load-config option to the mxmlc compiler to specify the air-config.xml file, which specifies to include the libs/air directory in the library path.

Unzip the Flex 3 SDK

Unzip install_root/resources/flex_sdk/flex_sdk_3.zip to install_root/resources/flex_sdk, where install_root is the BlazeDS installation directory. For example, the default value of install_root is c:\blazeds on Microsoft Windows.

Specifying the services-config.xml file in a compilation

When you compile your Flex application, you typically specify the services-config.xml configuration file to the compiler. This file defines the channel URLs that the client-side Flex application uses to communicate with the BlazeDS server. Then the channel URLs are compiled into the resultant SWF file.

Both client-side and server-side code use the services-config.xml configuration file. If you change anything in services-config.xml, you usually have to recompile your client-side applications and restart your server-side application for the changes to take effect.

In Flex Builder, the appropriate services-config.xml file is included automatically based on the BlazeDS web application that you specified in the configuration of your Flex Builder project. When you use the mxmlc compiler, use the services option to specify the location of the file.

Note: You can also create channel definitions at run time in ActionScript. In that case, you might be able to omit the reference to the services-config.xml configuration file from the compiler. For more information, see Run-time configuration.

Specifying the context root in a compilation

The services-config.xml configuration file typically uses the context.root token to specify the context root of a web application. At compile time, you use the compiler context-root option to specify that information.

During a compilation, Flex Builder automatically sets the value of the context.root token based on the BlazeDS web application that you specified in the configuration of your project. When you use the mxmlc compiler, use the context-root option to set it.

Using Flex Builder to compile client-side code

Adobe Flex Builder is an integrated development environment (IDE) for developing applications that use the Adobe Flex framework, MXML, Adobe Flash Player 9, AIR 1.0, ActionScript 3.0, BlazeDS, and the Flex Charting components.

Flex Builder is built on top of Eclipse, an open-source IDE. It runs on Microsoft Windows, Apple Mac OS X, and Linux, and is available in several versions. Installation configuration options let you install Flex Builder as a plug-in to an existing Eclipse workbench installation, or to install it as a stand-alone application.

For more information, see Using Adobe Flex Builder 3.

Using stand-alone or plug-in configuration of Flex Builder

The Flex Builder installer provides the following two configuration options:

Plug-in configuration This configuration is for users who already use the Eclipse workbench, who already develop in Java, or who want to add the Flex Builder plug-ins to their toolkit of Eclipse plug-ins. Because Eclipse is an open, extensible platform, hundreds of plug-ins are available for many different development purposes.

Stand-alone configuration This configuration is a customized packaging of Eclipse and the Flex Builder plug-in created specifically for developing Flex and ActionScript applications. The stand-alone configuration is ideal for new users and users who intend to develop only Flex and ActionScript applications.

Both configurations provide the same functionality. You select the configuration when you install Flex Builder.

Most BlazeDS developers choose to use the Eclipse plug-in configuration. Then they develop the Java code that runs on the server in the same IDE that they use to develop the MXML and ActionScript code for the client Flex application.

Note: The stand-alone configuration of Flex Builder does not contain tools to edit Java code, however, you can install them. Select Help > Software Updates > Find and Install menu command to open the Install/Update dialog box. Then select Search For New Features To Install. In the results, select Europa Discovery Site, and then select the Java Development package to install.

If you aren't sure which configuration to use, follow these guidelines:

• If you already use and have Eclipse 3.11 (or later) installed, select the plug-in configuration. On Macintosh, Eclipse 3.2 is the earliest version.
• If you don't have Eclipse installed and your primary focus is on developing Flex and ActionScript applications, select the stand-alone configuration. This configuration also lets you install other Eclipse plug-ins, so you can expand the scope of your development work in the future.

Add the Flex SDK to Flex Builder

Before you can build your first BlazeDS application in Flex Builder, add the Flex SDK to Flex Builder. You perform this procedure only once.

1. Start Flex Builder.
2. Select Window > Preferences.
3. Select Flex > Installed Flex SDKs.
4. Click Add.
5. Specify install_root/resources/flex_sdk for the Flex SDK location in the Add Flex SDK dialog box, where install_root is the BlazeDS installation directory. For example, the default value of install_root is c:\blazeds on Microsoft Windows.
6. Specify BlazeDS as the Flex SDK name, and click OK.
7. (Optional) Select the BlazeDS entry to make it the default Flex SDK for new Flex projects.
8. Click OK.

Create a Flex Builder project

Use this procedure to create a Flex Builder project to edit one of the samples shipped with the Test Drive application. The procedure for creating and configuring a new project is almost the same as the following procedure.

For more information on the Test Drive application, see Running the BlazeDS sample applications.

1. Start Flex Builder.
2. Select File > New > Flex Project.
3. Enter a project name. You are editing an existing application, so use the exact name of the sample folder: testdrive-chat.
   Note: If you are creating an empty project, you can name it anything that you want.
4. If you unzipped flex-src.zip in the samples directory, deselect the Use Default Location option, and specify the directory as C:\blazeds\tomcat\webapps\samples\testdrive-chat, or wherever you unzipped the file on your computer.
   Note: By default, Flex Builder creates the project directory based on the project name and operating system. For example, if you are using the plug-in configuration of Flex Builder on Microsoft Windows, the default project directory is C:\Documents and Settings\USER_NAME\workspace\PROJECT_NAME.
5. Select the application type as Web application (runs in Flash Player) to configure the application to run in the browser as a Flash Player application.

   If you are creating an AIR application, select Desktop Application (Runs In Adobe AIR). However, make sure that you do not have any server tokens in URLs in the configuration files. In the web application that ships with BlazeDS, server tokens are used in the channel endpoint URLs in the WEB-INF/flex/services-config.xml file, as the following example shows:

   <endpoint url="https://{server.name}:{server.port}/{context.root}/messagebroker/streamingamf"
         class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
   
   

   You would change that line to the following:

   <endpoint url="http://your_server_name:8400/samples/messagebroker/streamingamf"
         class="flex.messaging.endpoints.StreamingAMFEndpoint"/>
   
   

6. Select J2EE as the Application server type.
7. Select Use Remote Object Access.
8. Select LiveCycle Data Services.
9. If the option is available, deselect Create Combined Java/Flex Project With WTP.
10. Click Next.
11. Deselect Use Default Location For Local LiveCycle Data Services Server.
12. Set the root folder, root URL, and context root of your web application.

    The root folder specifies the top-level directory of the web application (the directory that contains the WEB-INF directory). The root URL specifies the URL of the web application, and the context root specifies the root of the web application.

    If you are using a BlazeDS Turnkey installation, set the properties as follows:

    Root folder: C:\blazeds\tomcat\webapps\samples\

    Root URL: http://localhost:8400/samples/

    Context root: /samples/

    Modify these settings as appropriate if you are not using the Tomcat application server.

13. Make sure that your BlazeDS server is running, and click Validate Configuration to ensure that your project is valid.
14. Verify that the Compile The Application Locally In Flex Builder option is selected.
15. Clear the Output Folder field to set the directory of the compiled SWF file to the main project directory.

    By default, Flex Builder writes the compiled SWF file to the bin-debug directory under the main project directory. To use a different output directory, specify it in the Output Folder field.

16. Click Next.
17. Set the name of the main application file to Chat.mxml, and click Finish.

Configure your project to use the Flex SDK that ships with BlazeDS

1. Select the project, and select Project > Properties.
2. Select Flex Compiler.
3. Select the Use A Specific SDK option under Flex SDK version.
4. Select BlazeDS, or whatever you named the Flex SDK, when you performed the procedure in Add the Flex SDK to Flex Builder.
5. Click OK.

You can now edit, compile, and deploy an application that uses BlazeDS.

Edit, compile, and deploy a BlazeDS application in Flex Builder

1. Open src\Chat.mxml in your Flex Builder project.
2. Edit Chat.mxml to change the definition of the TextArea control so that it displays an initial text string when the application starts:

   <mx:TextArea id="log" width="100%" height="100%" text="My edited file!"/>
   
   

3. Save the file.

   When you save the file, Flex Builder automatically compiles it. By default, the resultant SWF file is written to the C:\blazeds\tomcat\webapps\samples\testdrive-chat\bin-debug directory, or the location you set for the Output directory for the project. You should have set the Output directory to the main project directory in the previous procedure.

   Note: If you write the Chat.SWF file to any directory other than samples\testdrive-chat, deploy the SWF file by copying it to the samples\testdrive-chat directory.
4. Make sure that you have started the samples database and BlazeDS, as described in Running the BlazeDS sample applications.
5. Select Run > Run to run the application.

   You can also request the application in a browser by using the URL http://localhost:8400/samples/testdrive-chat/index.html.

   Note: By default, Flex Builder creates a SWF file that contains debug information. When you are ready to deploy your final application, meaning one that does not contain debug information, select File > Export > Release Build. For more information, see Using Adobe Flex Builder 3.
6. Verify that your new text appears in the TextArea control.

Create a linked resource to the BlazeDS configuration files

While working on the client-side of your applications, you often look at or change the BlazeDS configuration files. You can create a linked resource inside a Flex Builder project to make the BlazeDS configuration files easily accessible.

1. Right-click the project name in the project navigation view.
2. Select New > Folder in the pop-up menu.
3. Specify the name of the folder as it will appear in the navigation view. This name can be different from the name of the folder in the file system. For example, type server-config.
4. Click the Advanced button.
5. Select the Link To Folder In The File System option.
6. Click the Browse button and select the flex folder under the WEB-INF directory of your web application. For example, on a typical Windows installation that uses the Tomcat integrated server, select: install_root/tomcat/webapps/samples/WEB-INF/flex.
7. Click Finish. The BlazeDS configuration files are now available in your Flex Builder project under the server-config folder.
   Note: If you change anything in services-config.xml, you usually have to recompile your client-side applications and restart your server-side application for the changes to take effect.

Using mxmlc to compile client-side code

You use the mxmlc command line compiler to create SWF files from MXML, ActionScript, and other source files. Typically, you pass the name of the MXML file that contains an <mx:Application> tag to the compiler. The output is a SWF file. The mxmlc compiler ships in the bin directory of the Flex SDK. You run the mxmlc compiler as a shell script and executable file on Windows and UNIX systems. For more information, see Building and Deploying Adobe Flex 3 Applications.

The basic syntax of the mxmlc utility is as follows:

mxmlc [options] target_file 

The target file of the compile is required. If you use a space-separated list as part of the options, you can terminate the list with a double hyphen before adding the target file.

mxmlc -option arg1 arg2 arg3 -- target_file.mxml

To see a list of options for mxmlc, use the help list option, as the following example shows:

mxmlc -help list

To see a list of all options available for mxmlc, including advanced options, use the following command:

mxmlc -help list advanced

The default output of mxmlc is filename.swf, where filename is the name of the target file. The default output location is in the same directory as the target, unless you specify an output file and location with the output option.

The mxmlc command line compiler does not generate an HTML wrapper. Create your own wrapper to deploy a SWF file that the mxmlc compiler produced. The wrapper embeds the SWF object in the HTML tag. The wrapper includes the <object> and <embed> tags, and scripts that support Flash Player version detection and history management. For information about creating an HTML wrapper, see Building and Deploying Adobe Flex 3 Applications.

Note: Flex Builder automatically generates an HTML wrapper when you compile your application.

Compiling BlazeDS applications

Along with the standard options that you use with the mxmlc compiler, use the following options to specify information about your BlazeDS application.

• services filename

  Specifies the location of the services-config.xml file.

• context-root context-path

  Sets the value of the context root of the application. This value corresponds to the {context.root} token in the services-config.xml file, which is often used in channel definitions. The default value is null.

Edit, compile, and deploy the Chat.mxml file

1. Unzip flex-src.zip in the blazeds\tomcat\webapps\samples directory, as described in Running the BlazeDS sample applications.
2. Open the file C:\blazeds\tomcat\webapps\samples\testdrive-chat\src\Chat.mxml in an editor. Modify this path as necessary based on where you unzipped flex-src.zip.
3. Change the definition of the TextArea control so that it displays an initial text string when the application starts:

   <mx:TextArea id="log" width="100%" height="100%" text="My edited file!"/>
   
   

4. Change the directory to C:\blazeds\tomcat\webapps\samples.
5. Use the following command to compile Chat.mxml:
   Note: This command assumes that you added the mxmlc directory to your system path. The default location is install_root\resources\flex_sdk\bin.

   mxmlc -strict=true 
       -show-actionscript-warnings=true 
       -use-network=true 
       -services=WEB-INF/flex/services-config.xml 
       -context-root=samples 
       -output=testdrive-chat/Chat.swf 
       testdrive-chat/src/Chat.mxml
   
   

   The compiler writes the Chat.swf file to the samples\testdrive-chat directory.

6. Start the samples database and BlazeDS as described in Running the BlazeDS sample applications.
7. Request the application by using the URL http://localhost:8400/samples/testdrive-chat/index.html.
8. Verify that your new text appears in the TextArea control.

Rather than keeping your source code in your deployment directory, you can set up a separate directory, and then copy Chat.swf to samples\testdrive-chat to deploy it.