Using RSLs with the Flex SDK

For this example you'll use the same source file, main.mxml, but this time compile it with the command tool, mxmlc. Because you'll be running a Flash application from the local file directory, make sure the directory you are creating for the application is listed in a Flash Player trust file.

Trust is required because the application needs to read an RSL which (for this tutorial) is a local resource. By default, Flex creates applications that run in the local-with-network sandbox, which aren't allowed to access local files. You didn't need to worry about this in the previous Flex Builder section because Flex Builder added your project directory to the trust file for you. You can configure your trust directory by using the Global Security Settings panel in the Flash Player Settings Manager. If you don't have the trust files set up properly, you will get an error like this one when you run the application:

SecurityError: Error #2148: SWF file 
file:///C|/tests/helloworld/main.swf cannot access local resource 
file:///C|/tests/helloworld/framework_3.0.0.477.swz. Only local-with-filesystem and trusted local SWF files may access local resources. 

As in Flex Builder, flex-config.xml is preconfigured with RSL information for framework.swc. To use the configured RSL information from flex-config.xml or other configurations files, you can use the -static-rsls option. The -static-rsls option is an easy way to switch between static linking and dynamic linking using RSLs. The setting -static-rsls=false enables all the -runtime-shared-library-path options that are found in configuration files, while -static-rsls=true ignores them all and statically links the application. The exception to this rule is if the -runtime-shared-library-path option appears on the command line, then it will not be ignored.

Now let's change the directory where you created your main.mxml source file. Enter the following at the command line:

>mxmlc main.mxml  -static-rsls=false 

This line will dynamically link main.mxml using the framework RSL information in flex-config.xml. You can tell the application is linked using an RSL because the size of main.swf is under 50K. Forgetting to copy the RSLs to the application directory is a common mistake. I won't copy the RSLs, so we can see what happens.

Please note that if framework_3.0.0.477.swz already exists in the Flash Player cache, you won't get an error because the RSL will be pulled from the cache instead of being read from the URL. If you want to play along with this part, remove all the RSLs from the Flash Player cache by using the Global Storage Settings panel in the Flash Player Settings Manager. Uncheck the option to "Store common Flash components to reduce download times" and click the Confirm button. Then click the "Store common Flash components to reduce download times" check box again to re-enable the cache.

After doing so, when you run main.swf, it displays the following error (see also Figure 10):

Error #2032: Stream Error. URL: file:///C|/tests/helloworld/framework_3.0.0.477.swf

Figure 10. If the RSLs are not cached or copied to the application directory, an error appears

If you are using the debug version of Flash Player, you will see this message. If you are using the release version of Flash Player, you will see the same error code but without the corresponding error text.

Let's take a look in the log file to see what happened. Beginning with Flash Player 9 Update 3, you cannot modify the log file location or name. The filename is flashlog.txt and its location is hard-coded, depending on your operating system. Table 1 lists the flashlog.txt file locations.

Table 1. Locations of flashlog.txt

Operating system	Log file location
Windows 95, 98, ME, 2000, XP	C:\Documents and Settings\username\Application Data\Macromedia\Flash Player\Logs
Windows Vista	C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs
Mac OS X	/Users/username/Library/Preferences/Macromedia/Flash Player/Logs/
Linux	/home/username/.macromedia/Flash_Player/Logs/

After you've located the log file, open it up. It should look something like this:

Error #2032: Stream Error. URL: file:///C|/tests/helloworld/framework_3.0.0.477.swz Failed to load RSL framework_3.0.0.477.swz Failing over to RSL framework_3.0.0.477.swf Error #2032: Stream Error. URL: file:///C|/tests/helloworld/framework_3.0.0.477.swf 

The first error states that framework_3.0.0.477.swz could not be found. Because there is a failover unsigned RSL configured in flex-config.xml, the application attempted to load framework_3.0.0.477.swf. But that file was not available either. After copying the RSLs to the same directory as the app and running it again, everything works as expected.

As we did with Flex Builder, let's add the rpc RSL—even though our application is not using any classes from this SWC—just to demonstrate how it is done.

You have a couple of options to choose from when configuring the RSL information. You can either use a configuration file or add the command to the command line. Following is an example of each method.

Specifying RSLs in configuration files

This example uses an application configuration file, main-config.xml, whose name is the same as the application but with "-config" appended. This file is automatically read by the compiler at compile time. If I didn't name the file after the application, it would be necessary to use the -load-config option to get the compiler to use the configuration file. First I create the initial contents of main-config.xml by copying the RSL information from flex-config.xml. Then I modify the code from there. Here is the configuration file:

<?xml version="1.0"?>
 <flex-config>
    <runtime-shared-library-path append="true" >
      <path-element>c:/flex_sdk_3_beta3/frameworks/libs/rpc.swc</path-element>
      <rsl-url>rpc_3.0.0.477.swz</rsl-url>
      <policy-file-url></policy-file-url>
      <rsl-url>rpc_3.0.0.477.swf</rsl-url>
      <policy-file-url></policy-file-url>
   </runtime-shared-library-path>
 </flex-config> 

Take special note of the append=true on the runtime-shared-library-path begin element. This causes the entry to be appended to any existing RSL entries in other configuration files instead of overwriting them. From the command line, enter the same command as you did last time. Only this time, rpc.swc will be dynamically linked:

>mxmlc main.mxml –static-rsls=false 

You can verify that the RPC RSLs are linked to the application correctly by running the application without copying the RSLs. You will see errors as before when the application attempts to load the RPC RSL.

If you later decide you want to statically link the application so you can debug the Flex framework code, just set -static-rsls back to true or leave it off the command line all together—since the value defaults to true.

Specifying RSLs on the command line

To link RSLs on the command line, use the -runtime-shared-library-path option. To get help for compiler options, enter mxmlc –help list details at the command line. The output for the -runtime-shared-library-path option is as follows:

-runtime-shared-library-path [path-element] [rsl-url] [policy-file-url] [rsl-url] [policy-file-url]     alias -rslp      (repeatable) 

The first argument of the option is the path of the SWC file (or an open directory that represents a SWC). The next argument is the URL of the RSL that will be used to load the RSL at runtime, followed by the policy file URL.

More than one SWC can be used as an RSL. This is done by adding a -runtime-shared-library-path option for each library. Here's an example of a command that specifies two RSLs:

>mxmlc main.xmml -runtime-shared-library-path=c:\flex_sdk_3_beta3\frameworks\libs\framework.swc,framework_3.0.0.477.swz,,framework_3.0.0.477.swf -runtime-shared-library-path= c:\flex_sdk_3_beta3\frameworks\libs\rpc.swc,rpc_3.0.0.477.swz,,rpc_30.189225.swf 

This example loads the framework RSL followed by the rpc RSL.

Page 5 of 6

Previous Page

Next Page