Every Flex application uses some aspects of the Flex framework, which is a relatively large set of ActionScript classes that define the infrastructure of a Flex application. If a client loads two different Flex applications, the application will likely load overlapping class definitions. This can be a problem for users who are on dialup or slow network connections. It also leads to the perception that Flex applications load more slowly than HTML-based applications.

To overcome these limitations, you can use framework RSLs with your Flex applications. These libraries are comprised of the Flex class libraries and can be used with any Flex application. Framework RSLs come in two versions: signed and unsigned. Signed framework RSLs are cached in a special Player cache rather than the browser cache. They can be accessed by any application regardless of that application's originating domain. They only need to be downloaded to the client once, and they are not cleared from the client's disk when the browser's cache is cleared. Unsigned framework RSLs are cached in the browser cache and can only be used by applications that have access to the RSL's domain.

Flash Player 9.0.115 and later support loading signed framework RSLs. These RSLs can be loaded by applications in different domains. The framework RSLs are signed and have the extension SWZ. Only Adobe can create signed RSLs, and only signed RSLs can be stored in the Player cache. If you create an RSL that contains a custom library, it will be unsigned. You cannot sign it. If a Player with a version earlier than 9.0.115 attempts to load a framework RSL, then Flash Player skips it and loads a failover RSL, if one was specified when the application was compiled.

Only applications compiled with the Flex 3 compilers can use signed framework RSLs. Applications compiled earlier versions of the compilers cannot use signed framework RSLs.

Included framework RSLs

The framework RSLs are located in the flex_sdk_dir/frameworks/rsls directory. For Flex Builder, the framework RSLs are located in the flex_builder_dir/sdks/3.0.0/frameworks/rsls directory. The naming convention includes the version number of Flex, plus the build number of the compiler that you currently use. The following framework RSLs are included with the Flex products:

• framework_3.0.build_number.swz (signed framework RSL)
• framework_3.0.build_number.swf (unsigned framework RSL)
• rpc_3.0.build_number.swz (signed data services RSL)
• rpc_3.0.build_number.swf (unsigned data services RSL)
• (Flex Builder only) datavisualization_3.0.build_number.swz (signed data visualization RSL)
• (Flex Builder only) datavisualization_3.0.build_number.swf (unsigned data visualization RSL)

The signed and unsigned framework RSLs are optimized, as described in Optimizing RSL SWF files.

Flex also includes a number of SWC files that you can use as standard or cross-domain RSLs. These libraries are unsigned and not optimized. These SWC files are located in the frameworks/libs directory. They include automation.swc (for automation classes) and qtp.swc (for Mercury QuickTest Pro agent classes).

Framework RSL digests

After the framework RSLs are transferred across the network, Flash Player generates a digest of the framework RSL and compares that digest to the digest that was stored in the Flex application when it was compiled. If the digests match, then the RSL is loaded. If not, then Flash Player throws an error and attempts to load a failover RSL.

Using a framework RSL

To use the framework RSL in your Flex applications, you compile against the framework.swc file in your /frameworks/libs directory with the runtime-shared-library-path option on the command line. You can optionally add a policy file URL if necessary, plus one or more failover RSLs and their policy file URLs.

The following example compiles SimpleApp with the framework RSL:

mxmlc -runtime-shared-library-path=libs/framework.swc,
    framework_3.0.183453.swz,,framework_3.0.183453.swf
    SimpleApp.mxml

This example sets the signed framework RSL (*.swz) as the primary RSL, and then the unsigned framework RSL (*.swf) as the secondary RSL. This example does not specify a location for the policy file, so it is assumed that either the RSLs and the application are in the same domain or the policy file is at the root of the target server.

The following example shows the configuration file that loads a framework RSL:

<runtime-shared-library-path>
    <path-element>libs/framework.swc</path-element>
    <rsl-url>framework_3.0.${build.number}.swz</rsl-url>
    <policy-file-url></policy-file-url>
    <rsl-url>framework_3.0.${build.number}.swf</rsl-url>
</runtime-shared-library-path>

The configuration file uses a {build.number} token in the name of the RSLs. The compiler replaces this with a build number during compilation. The name of the framework RSL depends on the build number of Flex that you are using.

You can specify a signed SWZ file as the framework RSL and not specify an unsigned SWF file as a failover RSL. In this case, the application will not work in any Flash Player of version earlier than 9.0.115. The compiler will throw a warning, though, unless you set the target-player compiler option to 9.0.115 or later. This instructs the compiler to ignore the fact that there is no failover that will work with older Players. You can detect and upgrade users to the newest Player in the HTML wrapper by using the Express Install feature. For more information, see Using Express Install.

When you deploy your application, you must be sure to deploy the SWZ file to the location you specified on the command line. You must also be sure that the crossdomain.xml file is in place at the RSL's domain. To ensure that your Flex application can support older versions of Flash Player, you should also deploy the unsigned framework RSL SWF file (in addition to the signed SWZ file), and specify that file as a failover RSL.

About the Player cache

The Player cache stores signed RSLs, such as the framework RSLs. You can manage the settings of the Player cache with the Settings Manager. The use of the RSLs in the Player cache is secure; no third party can inject code that will be executed. Only Adobe can sign RSLs; therefore, only Adobe RSLs can be stored in the Player cache.

The default size of the framework cache is 20MB. When the aggregate size of the cached RSLs in this directory meets or exceeds 20MB, Flash Player purges the cache. Files are purged on a least-recently-used basis. Less-used files are purged before files that have been used more recently. Purging continues until the cache size is below 60% of the maximum size. By default, this is 12MB.

The Global Storage Settings panel in the Settings Manager lets the user turn off the caching feature and increase or decrease its size. The Settings Manager is a special control panel that runs on your local computer but is displayed within and accessed from the Adobe website. If the user disables the Player cache, then Flash Player will not load SWZ files. Flash Player will load failover RSLs instead.

The following table shows the locations of the Player cache on various platforms:

Using the framework RSLs in Flex Builder

You can use Flex Builder to organize your RSLs and decide which SWC files to use as RSLs and which to use as statically-linked libraries. You can also use Flex Builder to configure the deployment locations, digests, and other properties of RSLs. The signed and unsigned framework RSLs have already been created for you and optimized. All you have to do is compile your application against the RSLs and deploy them to the location that you specified at compile time.

You can set each SWC file that your project uses to use one of the following linkage types:

• Merged Into Code --Indicates that classes and their dependencies from this library are added to the SWF file at compile time. They are not loaded at run time. The result is a larger SWF file, but no external dependencies. This is the default selection for the framework.
• RSL -- Indicates that this library will be used as an RSL. When you compile your application, the classes and their dependencies in this library are externalized, but you compile against them. You must then make them available as an RSL at run time.
• External -- Indicates that this library will be externalized from the application, but it will not be used as an RSL. This excludes all the definitions in a library from an application but provides compile time link checking. Typically, only playerglobal.swc has this setting in an application project, but you might also use it to externalize assets that are used as modules or dynamically-loaded SWF files.

By default, all SWC files in the library path use the same linkage as the framework.

Use the framework.swc file as an RSL in Flex Builder

1. Open your Flex project in Flex Builder.
2. Select the project in the Navigator and select Project > Properties.
3. Select the Flex Build Path option in the resource list at the left. The Flex Build Path dialog box appears.
4. Select the Library Path tab:

   

5. Select Runtime Shared Library (RSL) from the Framework Linkage drop-down list. This instructs the application compiler to use the framework.swc file as an RSL. Flex Builder assumes that you will deploy the framework RSLs to the same directory as the main application's SWF file.
6. Click OK to save your changes.

When you export the release build of your project, the main application's SWF file should be smaller. In addition, in the release output directory, Flex Builder includes the framework's SWF and SWZ files for you to deploy.

You can view the settings of the SWC files that are included with Flex but whose classes are not included in the framework RSLs by expanding the list of libraries used by Flex in the Library Path tab. This list includes the automation.swc and qtp.swc files. You might want to compile your application against these SWC files as RSLs if your application will benefit from doing so. These SWC files are not optimized, so before you use them as RSLs, you should optimize them as described in Optimizing RSL SWF files.

Use other Adobe SWC files as RSLs in Flex Builder

1. On the Library Path tab, click the + to expand the list of SWC files.
2. Select the SWC file that you want to use as an RSL and click the + to show its properties. For example, click the + next to the automation.swc file.
3. Click the Link Type property and click the Edit button. The default link type is "Merged into code", which means that the library is statically linked to your application by default.
4. If you are already using the framework.swc file as an RSL, you can select the Use Same Linkage As Framework option. This option lets you toggle the RSL's status on and off by changing only the framework.swc file's linkage status. Otherwise, select Runtime Shared Library (RSL) from the Link Type drop-down list.

   The RSL Options field is enabled.

5. Select the Verification type and the deployment locations of the RSL as described in Compiling applications with standard and cross-domain RSLs.
6. Click OK to save your changes.

In some cases, you might not want to deploy the framework RSLs in the same directory as your main application. You might have a central server where these RSLs are stored, and need to share them across multiple applications.

Customize the deployment location of the framework RSLs

1. Edit the framework.swc file's settings in the Library Path Item Options dialog box.

   

2. Select the Digests radio button, if it is not already selected.

   Notice the two default entries in the Deployment paths field: an SWZ file and an SWF file. The SWZ file is the signed RSL that can be stored in the framework cache. The SWF file is an unsigned SWF file that is a failover if the SWZ file cannot be loaded.

   By default, the framework RSLs are deployed to the same directory as your main application.

3. To change the deployment location of the framework RSLs, click the SWZ file and then click the Edit button. The Edit RSL Deployment Path dialog box appears:

   

   In the Deployment Path/URL field, enter the location of the SWZ file. For example, "http://www.remoteserver.com/rsls/framework_3.0.183453.swc". The application tries to load the RSL from this location at run time. The location can be relative to the application's SWF file, or a full URL to a remote server. If the RSL is on a remote server, you might also be required to point to the policy file. In the Policy file URL field, enter the location of the crossdomain.xml file, if there is no crossdomain.xml file at the target server's root. You do not need to enter anything in this field if the application's SWF file and the RSLs are served from the same domain, or if the crossdomain.xml file is at the target server's root.

4. Click OK to save your changes in the Edit RSL Deployment Path dialog box.
5. Repeat the previous two steps for the SWF file, if you are also deploying the unsigned framework RSL with your application. If you do not deploy the failover SWF file, then users with Flash Player versions earlier than 9.0.115 will not be able to use your application.
6. Click OK to save your changes to the Library Path Item Options dialog box.
7. Ensure that the Verify RSL Digests option on the Library Path tab is selected.
8. Click OK to save your changes to the Flex Build Path settings.

When you deploy your application, you must manually copy the framework RSLs to the path that you specified on the remote server.

Using the framework RSLs on the command line

The following example application shows how to use the framework RSLs on the command line.

You first create an application that uses at least one visual Flex component. For example, the following application uses a Button control:

<?xml version="1.0"?> 
<!-- rsls/SimpleRSLApp.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Button label="Submit"/>     
</mx:Application>

Save this file as SimpleApp.mxml and store it in the project/src directory.

After you create the application, determine the size of the application's compiled SWF file before you use the framework RSL. This will give you an idea of how much memory you are saving by using the framework RSL.

Compile this application as you normally would, with one exception. Add the static-link-runtime-shared-libraries=true option; this ensures that you are not using the framework RSL when compiling the application, regardless of the settings in your configuration files. Instead, you are compiling the framework classes into your SWF file.

With the mxmlc command-line compiler, use the following command to compile the application:

cd project
mxmlc -static-link-runtime-shared-libraries=true bin/SimpleApp.mxml

Examine the output size of the SWF file. Even though the application contains only a Button control, the size of the SWF file should be around 140KB. That is because it not only includes component and application framework classes, but it also includes all classes that those classes inherit from plus other framework dependencies. For visual controls such as a Button, the list of dependencies can be lengthy. If you added several more controls to the application, you will notice that the application does not get much larger. That is because there is a great deal of overlap among all the visual controls.

Run the application in a browser either from the file system or from a server. You can also run the application in the standalone player.

Next, compile the application again, but this time add the signed framework RSL as an RSL and the unsigned framework RSL as a failover RSL. For example:

mxmlc -runtime-shared-library-path=c:/p4/flex/flex/sdk/frameworks/libs/framework.swc,
    framework_3.0.183453.swz,,framework_3.0.183453.swf rsls/SimpleApp.mxml

The result is a SWF file that should be significantly smaller than the previous SWF file.

This command includes a blank entry for the policy file URL. In this example, the crossdomain.xml file is not needed because you will deploy the RSLs and the application to the same domain, into the same directory.

In addition, the runtime-shared-library-path option includes an unsigned failover RSL as its final parameter. This is a standard framework RSL SWF file that is provided to support older versions of Flash Player that do not support signed RSLs. It is not cross domain, and if used by the client, it is stored in the browser's cache, not the framework cache.

You must now deploy the application and the framework RSLs to a server. You cannot request the SimpleApp.swf file from the file system because it loads network resources (the framework RSLs) and this will cause a security sandbox violation unless it is loaded from a server. You deploy the SimpleApp.swf, framework_3.0.183453.swz, and framework_3.0.183453.swf files to the same directory on your web server.

Request the application in the browser or create a wrapper for the application and request that file.

To verify that the signed framework RSL was loaded by your Flex application, you can look for an SWZ file in your framework cache. For more information, see About the Player cache.

After the client downloads the signed framework RSL, they will not have to download that RSL again for any Flex application that uses signed framework RSLs, unless a new version of the framework is released or the RSL's SWZ file is purged from the Player cache.