Using standard and cross-domain RSLs

Standard and cross-domain RSLs are RSLs that you create from your custom component libraries. These RSLs are different from signed framework RSLs in that they are unsigned and can only be stored in the browser’s cache. They are never stored in the Player cache.

To use standard or cross-domain RSLs, you perform the following tasks:

Create a library
An RSL is created from a library of custom classes and other assets. You can create a library with either the Flash Builder Library Project or the compc command-line compiler. You can output the library as a SWC file or an open directory. The library includes a library.swf file and a catalog.xml file; the library.swf file is deployed as the RSL. For more information, see Creating libraries.

Compile your application against the library
When you compile your application, you externalize assets from your application that are defined in the RSL. They can then be linked at run time rather than at compile time. You do this when you compile the application by passing the compile-time location of the library SWC file as well as the run-time location of the library’s SWF file. For more information, see Compiling applications with standard and cross-domain RSLs.

Optimize the RSL
After you generate a library and compile your application against it, you should run the optimizer against the library’s SWF file. The optimizer reduces the SWF file by removing debugging code and unneeded metadata from it. While this step is optional, it is best practice to optimize a library SWF file before deploying it. For more information, see Optimizing RSL SWF files.

Deploy the RSL
After you have compiled and optionally optimized your RSL, you deploy the library.swf file with your application so that it is accessible at run time. If the RSL is a cross-domain RSL, then you might also be required to deploy a crossdomain.xml file.

About standard RSLs

Standard RSLs can only be used by applications that are in the same domain as the RSL. You can benefit from using standard RSLs if you meet all of the following conditions:

  • You host multiple applications in the same domain.

  • You have custom component libraries.

  • More than one application uses those custom component libraries.

Not all applications can benefit from standard RSLs. Applications that are in different domains or that do not use component libraries will not benefit from standard RSLs.

Standard RSLs can benefit from digests. While they do not require digests, you can use them to ensure that your application loads the latest RSL. For more information, see About RSL digests.

The following is a list of typical applications that can benefit from standard RSLs:

  • Large applications that load multiple smaller applications that use a common component library. The top-level application and all the subordinate applications can share components that are stored in a common RSL.

  • A family of applications on a server built with a common component library. When the user accesses the first application, they download an application SWF file and the RSL. When they access the second application, they download only the application SWF file (the client has already downloaded the RSL, and the components in the RSL are used by the two applications).

  • A single monolithic application that changes frequently, but has a large set of components that rarely change. In this case, the components are downloaded once, while the application itself might be downloaded many times. This might be the case with charting components, where you might have an application that uses you change frequently, but the charting components themselves remain fairly static.

About cross-domain RSLs

Cross-domain RSLs can be used by applications in any domain or sub-domain. The benefits of cross-domain RSLs are the same as standard RSLs, but they are not restricted to being in the same domain as the application that loads them. This lets you use the same RSL in multiple applications that are in different domains.

To use a cross-domain RSL that is located on a remote server, the remote server must have a crossdomain.xml file that allows access from the application’s domain. The easiest way to do this is to add a crossdomain.xml file to the server’s root. To ensure that applications from any domain can access the RSL SWF file, you can use an open crossdomain.xml file such as the following:

<cross-domain-policy> 
    <site-control permitted-cross-domain-policies="all"/> 
    <allow-access-from domain="*" to-ports="*"/> 
</cross-domain-policy>

This is not a best practice, however, because it allows requests from any domain to load the RSL, and other assets, from your server. You should instead restrict requests to only those domains that you trust by narrowing the entries in the domain attribute. You should also consider using a more restrictive meta-policy with the permitted-cross-domain-policies attribute. For more information, see Using cross-domain policy files.

You can store the crossdomain.xml file anywhere on the target server. When you compile a cross-domain RSL, you can specify the location of the crossdomain.xml file, and the application will look to that location to get permission to load the RSL. If you do not specify the location of the crossdomain.xml file when you compile your application, the application looks in the server’s root directory by default.

Cross-domain RSLs can fail to load into an application under the following conditions:

  • The server on which the RSL is located fails

  • The network fails, so remote files cannot be loaded

  • The digest of the RSL when the application was compiled does not match the digest of the RSL when it is loaded

  • The policy file is absent from the RSL’s server, or that server has a restrictive meta-policy

Cross-domain RSLs support a backup mechanism where a failover RSL can be loaded in the case of a server failure. If the server on which the main RSL fails, Flash Player will try to load a failover RSL whose location you specify when you compile the application.

About RSL digests

To ensure that the cross-domain RSL is coming from the trusted party, Flash Player reads the bytes of the incoming RSL and computes a one-way hash, or digest. The digest must match the digest that was stored in the application at compile time when the application was linked to the cross-domain RSL. If the RSL’s digest matches the known digest, then Flash Player loads the cross-domain RSL. If the digests do not match, Flash Player displays an error message and does not load the RSL.

You can also use digests for standard RSLs. This is useful if you update your RSLs frequently, and want to ensure that the application loads the latest RSL.

To create a digest while compiling a library, you set the compute-digest compiler option to true. You can set this value in the flex-config.xml file, as the following example shows:

<compute-digest>true</compute-digest>

The default value of the compute-digest option is true.

In Flash Builder, to disable digests, you must add the following to the Additional Compiler Arguments field in the Flex Library Compiler dialog box:

-compute-digest=false

The compiler writes the digest inside the swc/libraries/library/digests element of the RSL’s catalog.xml file. The following example shows the structure of digest elements, which are optional children of the digests element in the catalog.xml file:

<digests> 
    <digest type="SHA-256" signed="true" 
        value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"/> 
    <digest type="SHA-256" signed="false" 
        value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"/> 
</digests>

The following table describes the tag and its attributes:

Option

Description

digest

Optional child of digests element.

signed

Whether the library is signed or not. This value is true if the digest is of a signed library and false otherwise. Only Adobe can create signed libraries. This attribute is required.

type

The kind of hash used to create the digest. The only currently-supported value is "SHA-256". This attribute is required.

value

The hash of the specified type. This is the digest of the RSL associated with the catalog.xml. This attribute is required.

When you compile your production application with an RSL that uses a digest for verification, set the verify-digests compiler option to true to indicate that the application must check the digest before using the RSL. The default value of this option is true.

If you have multiple RSLs, such as a main RSL plus a failover RSL, the compiler stores multiple digests inside the application.

The Flex compiler uses the SHA-256 digest algorithm from the java.security libraries to generate the digest.

About failover

The failover feature is used for two reasons:

  • If the Flash Player is not at least version 9.0.115 and it tries to load a signed RSL, it will attempt to load the failover RSL. (Flex 4 applications require Player 10.0 or later, so this might not be an issue for you.)

  • If a network or server failure occurs while loading the main RSL, Flash Player will attempt to load the failover RSL.

For framework RSLs, you typically specify a signed RSL as the main RSL, and an unsigned RSL as the failover RSL. When loading an application that uses signed framework RSLs, older versions of Flash Player skip the signed RSL and attempt to load the failover RSL, which is typically an unsigned RSL.

For all RSLs, the failover RSL provides a mechanism to load an RSL if the primary server is unavailable.

You can specify the location of the RSL and a failover RSL in your flex-config.xml file or on the command line as parameters to the runtime-shared-library-path option. The default failover RSL is framework_4.0.${build.number}.swf. In Flash Builder, you can add failover RSLs by adding them to the Deployment Paths in the Library Path Item Options dialog box.

Compiling applications with standard and cross-domain RSLs

Compiling your application with standard or cross-domain RSLs is easier to do in Flash Builder than it is on the command line. Flash Builder can automatically extract the RSL SWF file for you during the compilation process, and use that SWF to compile your application against. If you use the command-line compiler, then you must extract this file from the SWC file yourself prior to deployment. In either case, when you deploy the RSL SWF file, you should optimize it as described in Optimizing RSL SWF files.

Compile with standard or cross-domain RSLs in Flash Builder

  1. Open your application’s project.

  2. Select Project > Properties.

  3. Select Flex Build Path in the option list. The Flex Build Path settings appear.

  4. Select the Library Path tab.

  5. Click the Add SWC button. The Add SWC dialog box appears.

  6. Enter the path to the SWC file or click the Browse button to find the SWC file.

  7. Click OK to add the SWC file to your project’s library path. Flash Builder adds the new SWC file to the list of SWC files in the Library Path tree.

  8. Expand the SWC file in the Build Path Libraries tree by clicking the + next to it.

  9. Change the Link Type to “Runtime shared library (RSL)”. You do this by selecting the Link Type and clicking the Edit button. When you change the Link Type to an RSL, Flash Builder displays additional options in the Library Path Item Options dialog box.

  10. For Verification, select Digests if you are using a cross-domain RSL or if you are using a standard RSL that you want to verify at run time with a digest.

    Click the Add button to add the deployment path of the RSL SWF file. The Edit RSL Deployment Path dialog box appears.

    In the Deployment Path/URL field, enter the location that you will deploy the RSL’s SWF file to. This path is relative to the main application’s SWF file. The default is to deploy the RSL in the same directory as the main application.

    (Cross-domain RSLs only) Add a policy file URL if the application and the RSL will be on separate domains, and the crossdomain.xml file is not at the root of the RSL’s server.

    You can have Flash Builder extract the RSL’s SWF file from the SWC file automatically or you can do it manually. Deselect the Auto Extract swf to Deployment Path option if you want to extract the RSL’s SWF file from the SWC file manually. Otherwise, Flash Builder will extract the SWF file for you. In general, you should manually extract the SWF file and optimize it before deploying it. Otherwise, the library.swf file will be larger than necessary. For more information on optimizing the RSL, see Optimizing RSL SWF files.

    Click OK to save your changes.

  11. Select None for Verification if you are using a standard RSL that does not use a digest. In this case, the RSL is assumed to not be cross-domain, and you therefore cannot specify a policy file URL. This is because standard RSLs must be deployed in the same domain as the main application, so policy files are not necessary. The deployment path of the RSL can also only be a local path that is relative to the location of the main application’s SWF file.

  12. Click OK to save your Library Path Item Options.

  13. If the RSL is a cross-domain RSL, ensure that the Verify RSL Digests option is selected in the Library Path tab. If the RSL is standard and you do not want to use a digest, deselect this option. This option is overridden by the Verification setting in the Library Path Item Options dialog box.

  14. Click OK to save your changes to the Flex Build Path settings.

Compile with standard or cross-domain RSLs on the command line

To use standard or cross-domain RSLs in your application on the command line, you use the runtime-shared-library-path application compiler option. This option has the following syntax:

-runtime-shared-library-path=path-element,rsl-url[,policy-file-url,failover-url,...]

The following table describes the runtime-shared-library-path arguments:

Argument

Description

path-element

Specifies the location of the SWC file or open directory to compile against. For example, c:\flexsdk\frameworks\libs\framework.swc. The compiler provides compile-time link checking by using the library specified by this option.

This argument is required.

rsl-url

Specifies the location of the RSL SWF file that will be loaded by the application at run time. The compiler does not verify the existence of the SWF file at this location at compile time. It does store this string in the application, however, and uses it at run time. As a result, the SWF file must be available at run time but not necessarily at compile time. You specify the location of the SWF file relative to the deployment location of the application. For example, if you store the library.swf file in the web_root/libraries directory on the web server, and the application in the web root, you specify libraries/library.swf for the RSL SWF file.

This argument is required.

You must know the deployment location of the RSL SWF file relative to the application when you compile it. You do not have to know the deployment structure when you create the library SWC file, though, because components and classes are compiled into a SWC file and can be used by any application at compile time.

The value of the rsl-url argument can be a relative URL, such as “../libraries/library.swf”, or an absolute URL, such as “http://www.mydomain.com/libraries/library.swf”. If it is on a different server, it must be a cross-domain or framework RSL. Standard RSLs can only be loaded from the same domain as the application.

The default name of the RSL SWF file is library.swf, but you can change it to any name you want after you extract it from the SWC file. If you change it, then you must change the name you specify in the rsl-url option.

policy-file-url

Specifies the location of the policy file (crossdomain.xml) that gives permission to load the RSL from the server. For example, http://www.mydomain.com/rsls/crossdomain.xml. This is only necessary if the RSL and the application that uses it are on different domains. If you are serving the application and the RSL SWF file from the same domain, then you do not need to specify a policy file URL.

This argument is optional.

If you do not provide a value, then Flash Player looks at the root of the target web server for the crossdomain.xml file. For more information on using RSLs in different domains, see About cross-domain RSLs.

failover-url

Specifies the location of a secondary RSL if the first RSL cannot be loaded. This is most commonly used to ensure that an unsigned framework RSL will be used if the signed framework RSL fails to load. If the version of Flash Player is earlier than 9.0.115, it cannot load signed RSLs, so it must load an unsigned RSL. (Flex 4 applications require Player 10.0 or later, so this might not be an issue for you.)

While this argument is used primarily to ensure that the framework RSL is loaded, it can also be used by cross-domain RSLs to ensure that a secondary RSL is available in case of network or server failure.

This argument is optional.

If you specify a second policy-file-url, then Flash Player will look to that location for the crossdomain.xml file for the failover RSL.

The following example shows how to use the runtime-shared-library-path option when compiling your application on the command line:

mxmlc -runtime-shared-library-path=../lib/mylib.swc,../bin/library.swf Main.mxml

Do not include spaces between the comma-separated arguments of the runtime-shared-library-path option on the command line.

Your application can use any number of RSLs. In Flash Builder, you add a list of RSLs on the Library Path tab. When using the command line, you add additional runtime-shared-library-path options. In both cases, the order of the RSLs is significant because base classes must be loaded before the classes that use them.

You can also use a configuration file to use RSLs, as the following example shows:

<runtime-shared-library-path> 
    <path-element>../lib/mylib.swc</path-element> 
    <rsl-url>../bin/library.swf</rsl-url> 
</runtime-shared-library-path>

In the previous example, the file structure at compile time looks like this:

c:/Main.mxml 
c:/lib/CustomDataGrid.swc

The deployed files are structured like this:

web_root/Main.swf 
web_root/bin/library.swf

If you are using a cross-domain RSL, you can also specify the location of the crossdomain.xml file, and the location of one or more RSLs to be used as a failover RSL. The following example specifies a full URL for the location of the RSL, and the locations of a crossdomain.xml file and failover RSL on the command line:

mxmlc -runtime-shared-library-path= 
    ../lib/mylib.swc, 
    http://www.my-domain.com/rsls/library.swf, 
    http://www.my-domain.com/rsls/crossdomain.xml, 
    http://www.my-other-domain.com/rsls/library.swf, 
    http://www.my-other-domain.com/rsls/crossdomain.xml 
    Main.mxml

In the configuration file, this would be represented as follows:

<runtime-shared-library-path> 
    <path-element>../lib/mylib.swc</path-element> 
    <rsl-url>http://www.my-domain.com/rsls/library.swf</rsl-url> 
    <policy-file-url>http://www.my-domain.com/rsls/crossdomain.xml</rsl-url> 
    <rsl-url>http://www.my-other-domain.com/rsls/library.swf</rsl-url> 
    <policy-file-url>http://www.my-other-domain.com/rsls/crossdomain.xml</rsl-url> 
</runtime-shared-library-path>

Toggling RSLs on the command line

When compiling an application that uses RSLs, the command-line compiler options can be unwieldy and difficult to read. It is generally easier to define RSLs in your configuration files. However, when you do that, it is not very easy to enable or disable them as you develop your application because you have to edit the configuration file any time you want to change the way the RSLs are compiled.

To enable the use of RSLs without editing the configuration file, set the value of static-link-runtime-shared-libraries to false. By doing this, you can toggle the use of RSLs from the command line without having to edit the configuration file or enter long sets of command-line options. The default value of this option is true.

While you typically set the value of the static-link-runtime-shared-libraries option on the command line, you can also set it in the configuration file. If you set any RSL values on the command line, then the value of the static-link-runtime-shared-libraries option in the configuration file is ignored.

Optimizing RSL SWF files

The default SWF file in your SWC files includes debugging code and metadata that increase the file size. The debugging code is necessary for the compiler to run, but is not necessary at run time unless you want to debug the RSL. You can remove the debug code and unnecessary metadata by using the optimizer tool. This should result in a smaller RSL.

If you use the optimizer tool, you must keep track of two separate library files: one for compiling (the larger, pre-optimized one) and one for deploying (the smaller, optimized one). You compile your main application against the non-optimized library but then deploy the optimized library so that it can be loaded at run time.

The optimizer tool is in the bin directory. For Unix and Mac OS, it is a shell script called optimizer. For Windows, it is optimizer.exe. You invoke it only from the command line. The Java settings are managed by the jvm.config file in the bin directory.

The syntax for the optimizer tool is as follows:

optimizer -keep-as3-metadata Bindable Managed ChangeEvent NonCommittingChangeEvent Transient -input input_swf -output output_swf

You must specify the keep-as3-metadata option and pass it the required metadata. At a minimum, you should specify the Bindable, Managed, ChangeEvent, NonCommittingChangeEvent, and Transient metadata names. You can also specify custom metadata that you want to remain in the optimized SWF file.

You can specify the configuration file that the optimizer tool uses by using the load-config option.

To get help while using the optimizer tool, enter the -help list advanced option:

optimizer -help list advanced

By default, the optimizer tool saves an optimized version of the SWF file in the current directory, with the name output.swf. This file should be smaller than the library.swf because it does not contain the debugging code.

Use optimized RSLs

  1. Create an RSL by compiling a library project in Flash Builder or building a SWC file with the compc command line tool.

  2. Compile your main application and reference the RSL.

  3. Extract the library.swf file from your RSL’s SWC file, if you haven’t done so already.

  4. Run the optimizer against the library.swf file, for example:

    optimizer -keep-as3-metadata Bindable Managed ChangeEvent NonCommittingChangeEvent Transient -input c:\rsls\library.swf -output c:\rsls\output\output.swf
  5. Run the digest tool against the optimized library.swf file; for example:
    digest -digest.rsl-file c:\rsls\output\output.swf -digest.swc-path c:\rsls\output\
  6. Deploy the optimized library (in this case, output.swf) with the application so that the application uses it at run time.

Example of creating and using a standard and cross-domain RSL

This example walks you through the process of creating a library and then using that library as a standard and a cross-domain RSL with an application. It uses the command-line compilers, but you can apply the same process to create and use RSLs with a Flash Builder project. This example first shows you how to use a standard RSL, and then how to use that same RSL as a cross-domain RSL.

Keep in mind that a SWC file is a library that contains a SWF file that contains run-time definitions and additional metadata that is used by the compiler for dependency tracking, among other things. You can open SWC files with any archive tool, such as WinZip, and examine the contents.

Before you use an RSL, first learn how to statically link a SWC file. To do this, you build a SWC file and then set up your application to use that SWC file.

In this example you have an application named app.mxml that uses the ProductConfigurator.as and ProductView.as classes. The structure of this example includes the following files and directories:

project/src/app.mxml 
project/libsrc/ProductConfigurator.as 
project/libsrc/ProductView.as  
project/lib/ 
project/bin/

To compile this application without using libraries, you can link the classes in the /libsrc directory using the source-path option, as the following example shows:

cd project/src 
mxmlc -o=../bin/app.swf -source-path+=../libsrc app.mxml

This command adds the ProductConfigurator and ProductView classes to the SWF file.

To use a library rather than standalone classes, you first create a library from the classes. You use the compc compiler to create a SWC file that contains the ProductConfigurator and ProductView classes, as the following command shows:

cd project 
compc -source-path+=libsrc -debug=false -o=lib/mylib.swc ProductConfigurator ProductView

This compiles the mylib.swc file in the lib directory. This SWC file contains the implementations of the ProductConfigurator and ProductView classes.

To recompile your application with the new library, you add the library with the library-path option, as the following example shows:

cd project/src  
mxmlc -o=../bin/app.swf -library-path+=../lib/mylib.swc app.mxml

This links the library at compile time, which does not result in any benefits of externalization. The library is not yet being used as an RSL. If you use the new library as an RSL, the resulting SWF file will be smaller, and the library can be shared across multiple applications.

Now you can recompile the application to use the library as an external RSL rather than as a library linked at compile time.

The first step is to compile your application with the runtime-shared-library-path option. This option instructs the compiler to specifically exclude the classes in your library from being compiled into your application, and provides a run time location of the RSL SWF file.

cd project/src  
mxmlc -o=../bin/app.swf -runtime-shared-library-path=../lib/mylib.swc,myrsl.swf app.mxml

The next step is to prepare the RSL so that it can be found at run time. To do this, you extract the library.swf file from the SWC file with any archive tool, such as WinZip or jar.

The following example extracts the SWF file by using the unzip utility on the command line:

cd project/lib 
unzip mylib.swc library.swf 
mv library.swf ../bin/myrsl.swf

This example renames the library.swf file to myrsl.swf and moves it to the same directory as the application SWF file.

The next step is to optimize the library.swf file so that it does not contain any debug code or unnecessary metadata. The following example optimizes the SWF file by using the optimizer tool:

optimimzer -keep-as3-metadata Bindable Managed ChangeEvent NonCommittingChangeEvent Transient 
    -input bin/myrsl.swf -output bin/myrsl.swf

You now deploy the main application and the RSL. In this example, they must be in the same directory. If you want to deploy the myrsl.swf file to a different directory, you specify a different path in the runtime-shared-library-path option.

You can optionally run the optimizer tool on the myrsl.swf file to make it smaller before deploying it. For more information, see Optimizing RSL SWF files.

To use the RSL as a cross-domain RSL, you add a crossdomain.xml file, a failover RSL, and its crossdomain.xml file to the option, as the following example shows:

cd project/src 
    mxmlc -o=../bin/app.swf -runtime-shared-library-path=../lib/mylib.swc, 
    http://www.my-remote-domain.com/rsls/myrsl.swf, 
    http://www.my-remote-domain.com/rsls/crossdomain.xml, 
    http://www.my-other-remote-domain.com/rsls/myrsl.swf, 
    http://www.my-other-remote-domain.com/rsls/crossdomain.xml, 
    Main.mxml

Next, you create a crossdomain.xml file. If the domain that are you running the application on is my-local-domain.com, then you can create a crossdomain.xml file that looks like the following:

<cross-domain-policy> 
    <site-control permitted-cross-domain-policies="all"/> 
    <allow-access-from domain="*.my-local-domain.com" to-ports="*"/> 
</cross-domain-policy>

You now deploy the main application and the RSL. This time, however, the RSL is deployed on a remote server in the /rsls directory. You must also ensure that the crossdomain.xml file is in that directory. Finally, you must ensure that the failover RSL and its crossdomain.xm l file are deployed to the other remote domain.