Using the framework RSLs

Every application built with Flex uses some aspects of the Flex framework, which is a relatively large set of classes that define the infrastructure of an application. If a client uses two different applications, the applications will likely load overlapping class definitions. The result is that applications are larger and load slower than they should. This can be a problem for users who are on dialup or slow network connections. It also leads to the perception that applications load more slowly than other web-based applications.

To overcome these limitations, Flex provides framework RSLs. These libraries are comprised of the Flex class libraries and can be used with any application built with Flex. The framework RSLs are precompiled libraries of framework classes and components.

Framework RSLs come in two versions: signed and unsigned.

  • Signed framework RSLs are cached in a special Player cache and in 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. When the browser’s cache is cleared, signed framework RSLs persist in the special Player cache.

  • Unsigned framework RSLs are cached in the browser cache and can only be used by applications that have access to the RSL’s source domain. When the browser’s cache is cleared, unsigned framework RSLs are removed just like any other file in the cache.

By default, framework RSLs are dynamically linked into your applications. When an application loads on the client, the client attempts to load the framework RSLs if they are not already in the client’s cache. Typically, they attempt to load the signed framework RSL that is hosted by Adobe first. The location and order of RSLs loaded is defined in the flex-config.xml file. You can override these values on the command line or by using the Flex Build Path properties panel in Flash Builder.

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. (Flex 4 applications require Player 10.0 or later, so this might not be an issue for you.)

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

Included framework RSLs

If your application uses framework RSLs, the client attempts to load them from Adobe first. If the Adobe site is unavailable, or the client’s network access is restricted, you can instruct the client to use the included framework RSLs instead.

The framework RSLs that are included in the SDK installation are located in the flex_sdk_dir/frameworks/rsls directory. For Flash Builder 4, the framework RSLs are located in the flash_builder_dir/sdks/4.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 4 products:

  • (Flash Builder only) datavisualization_4.0.0.build_number.swz (signed data visualization RSL)

  • (Flash Builder only) datavisualization_4.0.build_number.swf (unsigned data visualization RSL)

  • framework_4.0.0.build_number.swz (signed framework RSL)

  • framework_4.0.0.build_number.swf (unsigned framework RSL)

  • osmf_4.0.0.build_number.swz (signed OSMF RSL)

  • osmf_4.0.0.build_number.swf (unsigned OSMF RSL)

  • rpc_4.0.0.build_number.swz (signed data services RSL)

  • rpc_4.0.0.build_number.swf (unsigned data services RSL)

  • spark_4.0.0.build_number.swf (unsigned Spark components RSL)

  • spark_4.0.0.build_number.swz (signed Spark components RSL)

  • textLayout.build_number.swf (unsigned TLF RSL)

  • textLayout.build_number.swz (signed TLF RSL)

The SWZ and SWF files are files that you deploy. The SWC files in framework/libs are the files that you compile your application against.

The signed framework RSLs are optimized, as described in Optimizing RSL SWF files. This means that they do not include debugging information. Flash Builder automatically uses unoptimized debug RSLs when you launch the debugger. If you compile on the command line, however, and use the command line debugger, you must either disable RSLs or specify non-optimized RSLs to use. Otherwise, you will not be able to set break points or take advantage of other debugging functionality.

The framework RSLs for Flex 3 are also included in the sdks/3.4.0 directory.

Configuring framework RSLs

The Flex compilers compile against the framework RSLs by default. This means that all classes in the Flex framework are dynamically linked into your application SWF file, which should result in a smaller SWF file than if you statically linked in the library. In most cases, you do not have to specify which RSLs to use, or what order to use them in. The Flex compiler handles this for you.

The following framework RSLs are dynamically linked in by default:

  • textLayout.swc

  • framework.swc

  • spark.swc

  • rpc.swc

You can view the order of preference for the location of these RSLs and their failovers in the flex-config.xml file. The preference is to use hosted, signed RSLs first, with local signed RSLs second.

The following example shows an entry in the configuration file that loads one of the framework RSLs:

<runtime-shared-library-path> 
    <path-element>libs/framework.swc</path-element> 
    <rsl-url>${hosted.rsl.url}/flex/${build.number}/framework_${build.number}.swz</rsl-url> 
    <policy-file-url>${hosted.rsl.url}/crossdomain.xml</policy-file-url> 
    <rsl-url>framework_${build.number}.swz</rsl-url> 
    <policy-file-url></policy-file-url> 
</runtime-shared-library-path>

The configuration file uses a {hosted.rsl.url} token in the first <rsl-url> element. The compiler replaces this with the location of the signed framework RSLs on the Adobe web site. If the client does not have network access, Flash Player then attempts to load the RSL that is specified by the next <rsl-url> element in the list. In this case, it is the SWZ file in the same directory as the application.

The configuration file also 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 also manually specify framework RSLs for your applications. You do this by compiling against the SWC files 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_4.0.0.5902.swz,,framework_4.0.0.5902.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.

You can also specify the unsigned framework RSL as the primary RSL. This is common if you want to include debug information in the RSL, such as when you are using the command line to compile your SWF file and the command line debugger to debug it. Flash Builder automatically uses debug RSLs when you debug with it so you do not have to change any compiler options.

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. In the HTML wrapper, you can detect and upgrade users to the newest Player by using the Express Install feature. For more information, see Using Express Install in the wrapper. (Flex 4 applications require Player 10.0 or later, so this might not be an issue for you.)

If you use locally-hosted signed framework RSLs when you deploy your application, you must deploy the SWZ file to the location that 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 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.

Disabling framework RSLs

The use of framework RSLs is enabled by default. You can disable RSLs when you compile your application by setting the static-link-runtime-shared-libraries compiler option to true, as the following example shows:
mxmlc -static-link-runtime-shared-libraries=true MyApp.mxml

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 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.

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:

Platform

Location

Windows 95/98/ME/2000/XP

C:\Documents and Settings\user_name\Application Data\Adobe\Flash Player\AssetCache\

Windows Vista

C:\Users\user_name\AppData\Roaming\Adobe\Flash Player\AssetCache\

Linux

/home/user_name/.adobe/Flash_Player/AssetCache/

Mac OSX

/Users/user_name/Library/Cache/Adobe/Flash Player/AssetCache/

Using the framework RSLs in Flash Builder

Framework RSLs are enabled by default in Flash Builder. You can use the information in this section if you want to specify that only some of them are used, reorder the failover options, or customize some other aspect of the framework RSLs.

You can use Flash 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 Flash 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. By default, the Flex compiler dynamically links against these RSLs. For locally-hosted RSLs, you must also 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 one with no external dependencies.

  • 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 files as RSLs in Flash Builder

  1. Open your Flex project in Flash 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 files as RSLs.

  6. Click OK to save your changes.

In the release output directory, Flash Builder includes the framework’s SWF and SWZ files for you to deploy if your users require locally-hosted RSLs.

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 if you use them as RSLs, you should optimize them as described in Optimizing RSL SWF files.

Use other Adobe SWC files as RSLs in Flash Builder

  1. On the Library Path tab, click the + next to Flex 4.0 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 Link Type 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.

  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_4.0.0.5902.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. 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. (Flex 4 applications require Player 10.0 or later, so this might not be an issue for you.)

  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.

Example of using the framework RSLs on the command line

Framework RSLs are enabled by default for the command-line compiler. You can use the information in this section if you want to specify that only some of them are used, reorder the failover options, or customize some other aspect of the framework RSLs.

Create an application with a single Button control. 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 the 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 application’s SWF file.

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

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 over 100KB. 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_4.0.0.5902.swz,,framework_4.0.0.5902.swf rsls/SimpleApp.mxml

The result is a SWF file that should be 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.

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). This causes a security sandbox violation unless the application is loaded from a server. Deploy the SimpleApp.swf, framework_4.0.0.5902.swz, and framework_4.0.0.5902.swf files to the same directory on your web server.

Note: You can point to the SWZ files that are hosted on the Adobe web site, rather than deploy your own SWZ files as RSLs. In this case, view the default entries for the RSLs in the flex-config.xml file to see how to link to them.

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 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 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.