To create a Flex project with Java code in Flex Builder, follow these steps:

A Java and Flex project contains the following folder structure:

Figure 2.8. The Create a Flex project screen of the New Flex Project wizard contains a couple of tabs that let you add more source folders and libraries to your project if necessary.

Figure 2.9. Once the New Flex Project wizard is finished, the newly created Flex project appears in the Flex Navigator view, and the Main.mxml application file is opened in the editor.

Ensure that the Flex Development perspective is still open. Then, to create a Flex Library project, follow these steps:

Figure 2.11. On the second screen of the New Flex Library Project wizard, you can choose the ActionScript class folders as well as the folders containing nonembedded assets that are added to your library.

This project contains only two folders: an src folder that contains the source code for ActionScript and MXML files to be included in the library and a bin folder to hold the compiled SWC file created from the source code. Remember that an SWC file isn't something that runs on its own but instead contains code that's referenced by other MXML or ActionScript code that's compiled into an SWF application.

When you create this project, Flex Builder places a red X next to the project in the Flex Navigator view. If you click the Problems tab at the bottom of the workspace, you see that the red X indicates that there are no source code files included in the library. This makes sense because a library that includes nothing isn't much of a library! Once you add some ActionScript and MXML files to the src folder for this library project, you can add them to the classes included in the library by right-clicking the file and then choosing Include Class in Library from the popup menu.

It's useful to create a library when you have a set of ActionScript or MXML code that can be reused in several Flex applications. For example, you might create an ActionScript class that contains mathematical or string manipulation functions that you can use in multiple applications.

You can build, deploy, and test your Java and Flex projects all from within Flex Builder with a single command. There's a simple configuration change that's needed in order to set things up properly to allow this to work correctly.

In a Java Web application, a configuration file called web.xml contains information about the Web application, including definitions for any Java servlets, servlet filters (Java classes that are run before the servlets when a request is made to the server for a particular servlet), and other identifying information about the Web application.

One of the other things defined in web.xml is a set of welcome files. These files are the ones used if no specific file is given in a URL. Typically, index.html is the default welcome file. If you visit a URL such as www.somewebserver.com, the Web server uses the default welcome file to fulfill the request, so that the page you're actually visiting is www.somewebserver.com/index.html. In a Java Web application, you can specify multiple welcome files in the web.xml configuration file. The application server checks for each one of them in the order specified and then uses the first one it finds to fulfill the request.

When Flex Builder creates the Flex project for a Java and Flex application, it adds a default set of welcome files to the web.xml configuration file. However, none of these files actually exist in the project. The only HTML file that's created by Flex Builder when you create your Java and Flex project is a wrapper HTML file with the same name as your MXML application file. By default, Flex Builder names the MXML application file Main.mxml and the corresponding HTML file main.html. In order to deploy and run your project from inside Flex Builder, you must do one of two things:

Because this project is currently just a shell with no real application logic yet, adding the main.html file to the list of welcome files in the web.xml configuration file is the quickest way to get started with this project. To modify the web.xml configuration file and build, deploy, and run the project within Flex Builder, follow these steps:

When you click the Finish button to close the Run On Server dialog box, a few things happen:

You can see what the application running inside the Flex Builder Web browser looks like in Figure 2.14. It opens in its own tab in the editor view, alongside any source code files you have open in the editor.

The MXML file created by the New Flex Project wizard contains only empty opening and closing <mx:Application> MXML tags, so the resulting compiled SWF isn't very interesting. Close the Flex Builder Web browser by clicking the X on the right side of the tab.

Figure 2.13. The Run On Server dialog box lets you choose a server configuration to deploy and run your application on. The JBoss configuration you created previously appears here for you to use.

Figure 2.14. Using the Run On Server dialog box causes the application to be built and packaged into a WAR file, deployed to the JBoss application server, and launched in Flex Builder's built-in Web browser.

To give you a sneak preview of Flex development and show how Flex Builder makes it easy to redeploy your applications as you develop to see how they're progressing, add a few components to the MXML file by following these steps:

Redeploy and run the application by using the previous steps. This time, when the Web browser opens the application, you see the Button and TextInput controls you added to the application. Click the Button control, and you see the message you added to the Button control's on-click event appear in the TextInput control, as shown in Figure 2.17.

Figure 2.17. After adding some controls to the application, you can rebuild, deploy, and run it on the JBoss application server the same way you did before to see the updated version. Being able to update and run the application while developing helps you see how your application functions as you add more features and lets you correct problems as you go.

During Flex development, it's sometimes helpful to be able to see messages and inspect the code during runtime to diagnose any problems that arise. This is especially true in large applications, where many MXML and ActionScript files make up a single application and the application flows through code in many different files. Two means of examining what's going on in your code are adding trace messages and setting debugging breakpoints.

The trace() function in Flex allows you to print out messages to the console while running in Flex Builder so that you can see what's happening in an application at any given point. This is useful if, for example, your application code uses many different functions for a given feature and you want to print out a message in each one to be sure they're all being called — and in the proper order.

You typically don't leave trace messages in your final application — they're useful only during development, where you can see them being output in the Flex Builder console. In production applications, they only add unnecessary overhead.

To view trace messages in Flex Builder, your application must be running in Debug mode within Flex Builder. Debug mode allows you to inspect the output of any trace messages as well as set breakpoints in your application. A breakpoint pauses execution of the application at the selected location. You can use Flex Builder's Flex Debugging perspective to inspect the values of variables while the application is paused or to step through the application one line at a time to see what the code is doing. To debug with Flex Builder, your application must be compiled with debug information added. This increases the size of the final SWF file, so it's not recommended that this information be included in the final release version of your application. Flex Builder automatically compiles your Flex applications with debug information included for use in development. For production releases, you can create an optimized SWF file by choosing Project

To demonstrate using trace messages and debugging the application, you can change the click action of the Button control to call an ActionScript function that performs a few functions. Then, you can add a trace message to the ActionScript function and set a breakpoint to see how the debugger operates.

Click the Source button below the Main.mxml editor tab to switch the editor back to Source view. The MXML code for the Button and TextInput controls has been added to the source code. Add the following MXML block to the Main.mxml application just above the <mx:TextInput> tag:

<mx:Script>
     <![CDATA[
          private function setMessage(e:MouseEvent):void
          {
                  trace("entering setMessage function");
                  var buttonLabel:String = (e.target as Button).label;
                  var dateTime:Date = new Date();
                  var dateString:String = dateTime.
        toLocaleDateString();
                  var timeString:String = dateTime.
        toLocaleTimeString();
                theMessage.text = "Clicked " + buttonLabel + " on "
        + dateString + " at " + timeString;
                  trace("exiting setMessage function");
                }
         ]]>
    </mx:Script>

This code constructs a String based on the label of the button that was clicked as well as the date and time and then sets the text property of the TextInput control to that String. At the beginning and end of the function, Flex trace messages are output to the console. To tie this function to the clicking of the Button control, change the click attribute of the <mx:Button> tag to the following:

click="setMessage(event)"

To set a breakpoint in the code in Flex Builder, you simple double-click the left margin next to the line of code at which you want the application execution to pause. Double-click the left margin next to the second line of the setMessage() function where the value of the buttonLabel variable is set. You see a blue dot icon appear in the left margin, as shown in Figure 2.18.

Figure 2.18. When you set a breakpoint in Flex Builder, a blue dot icon appears in the margin to the left of the line containing the breakpoint. The highlighted line has this icon before it.

To run your application, follow the steps you previously used to build, deploy, and run the application on the JBoss server. Once the application is started, close the internal Flex Builder Web browser by clicking the X on the right side of the tab and then start up the debugger by following these steps:

Take a moment to explore the Flex Debugging perspective. In the top-right corner is a set of views that includes the Variables, Breakpoints, and Expressions views. The Variables view lets you see the current value of variables in your application at the point where the application has paused. The Breakpoints view lets you see and toggle your breakpoints on and off. The Expressions view lets you type expressions whose value you want to evaluate. In the Console view at the bottom of the screen, the trace message you set at the beginning of the setMessage() function has been output to the console.

Figure 2.20. The Flex Debugging perspective contains a number of views that let you inspect variable values, see and toggle breakpoints, and step through the code one line at a time.

To step to the next line of the application, press F6. As you step line by line through the application code, the Variables view updates the values of the variables as they're set. The first time you press F6, for example, the value of the buttonLabel variable changes from undefined to Get A Message! Step through the code line by line, and watch all the variable values change in the Variables view. When you reach the end of the function, the final trace message is printed out to the Console view. If you keep pressing F6, the debugger actually steps into the internals of the Flex framework. To continue running your application, press the green Run arrow button in the Debug view to the left of the Variables view.

Now switch to the Breakpoints view and then click the check box next to the breakpoint to toggle it off. Switch back to your Web browser and then click the Get A Message! button again. This time, the application doesn't stop, but going back into Flex Builder reveals that the trace messages still print out to the Console view. The ability to turn breakpoints on and off as needed comes in handy when stepping through a large body of code to try to pinpoint the location of a problem. You can have the application stop at some breakpoints and skip others while still keeping the locations of all breakpoints intact.

Using trace() is most appropriate during development by using the debug version of the Flash Player. However, you probably want to be able to also log errors and other information in your deployed applications. Flex includes a logging framework that allows you to write such information out to log files. Flex logging consists of two main components:

Changing the Main.mxml application to use the Flex logging framework requires only a few changes to the code. First, add the following code to the Main.mxml file just above the setMessage() function:

import mx.logging.*;
import mx.logging.targets.TraceTarget;

private function setupLogger():void
{
   var target:TraceTarget = new TraceTarget();

   // possible values: ALL, DEBUG, INFO, WARN, ERROR, FATAL
   target.level = LogEventLevel.ALL;
   target.includeCategory = true;

   // log the level
   target.includeLevel = true;

   // log the date and time
   target.includeDate = true;
   target.includeTime = true;

   Log.addTarget(target);
}

First, the Flex logging classes are imported into the Main.mxml application. This code uses the built-in TraceTarget. The setupLogger() function configures the target and adds it to the logger. This target logs messages at all levels (LogEventLevel.ALL), but you could specify a less verbose level of logging by choosing a specific value. Each level includes messages at that level or higher. For example, specifying LogEventLevel.WARN logs messages at the WARN, ERROR, and FATAL levels. The target is then configured to include category, level, date and time information along with the message being logged. Finally, the target is added to the logger.

To ensure that the setupLogger() function is executed when the application begins, add a creationComplete attribute to the <mx:Application> tag so that it matches the following code:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   creationComplete="setupLogger();" layout="absolute">

The creationComplete attribute specifies a function to be run once the application has been fully instantiated. Here, the setupLogger() function runs, and the logging framework is configured and ready to use.

Now change the two trace() statements in the setMessage() function to use the logger instead. The first statement changes from this:

trace("entering setMessage function");

to this:

Log.getLogger("main").debug("entering setMessage function");

This statement retrieves the logger for the category "main", referring to the Main.mxml application, and sends a debug level message. This message is sent to the TraceTarget added to the logger, which in turn outputs this message — along with the category, level, date, and time information — by using the trace mechanism.

Although this example uses the TraceTarget class, you could also implement a custom logging target that extends AbstractTarget and sends the output to a server (by using a Web service or other remote call, for example) or splits the output among multiple log files on the client machine. Using the logging framework rather than simply using trace() provides more flexibility for getting debug and error information from your deployed applications.