Google Git
Sign in
apache / flex-site / HEAD / . / content / doc / flex / using / flx_rsl_rsl.html
blob: 3fd70ee40b611cb87ad702e9dcebe38f4362e008 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="Runtime Shared Libraries"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7fd1_verapache"/>
<title>Runtime Shared Libraries</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7fd1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7fd1_verapache"><!-- --></a>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">Introduction to RSLs</h2>
<div>
<p>One
way to reduce the size of your applications' SWF files is by externalizing shared
assets into stand-alone files that can be separately downloaded
and cached on the client. These shared assets can be loaded and
used by any number of applications at run time, but are transferred
only once to the client. These shared files are known as <em>Runtime Shared Libraries</em> or <em>RSLs</em>. </p>
<p>When multiple applications share a core set of components or
classes, clients can download those assets only once as an RSL rather
than once for each application. The RSLs are persisted on the client
disk so that they do not need to be transferred across the network
a second time. The resulting file size for the applications can
be reduced. The benefits increase as the number of applications
that use the RSL increases.</p>
<p>Applications built with Flex support the following types of RSLs:</p>
<ul>
<li>
<p>Framework RSLs — Libraries of components and framework
classes that all applications can share. Framework RSLs are precompiled
for you. Adobe provides hosted, signed framework RSLs that you can
link to from any application that has internet access. For more
information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache">Using
the framework RSLs</a>.</p>
</li>
<li>
<p>Standard RSLs — A library of custom classes created by you
to use across applications that are in the same domain. Standard
RSLs are stored in the browser's cache. For more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7adf_verapache">About
standard RSLs</a>. </p>
</li>
<li>
<p>Cross-domain RSLs — A library of custom classes, like standard
RSLs, with the difference being that they can be loaded by applications
in different domains and sub-domains. Cross-domain RSLs are stored
in the browser's cache. For more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ae0_verapache">About
cross-domain RSLs</a>.</p>
</li>
</ul>
<p>You can create your own RSLs from custom libraries. You do this
by using the compc command-line compiler. </p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7f1e_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7f1e_verapache"><!-- --></a>
<h3 class="topictitle3">About linking</h3>
<div>
<p>Understanding
library linking can help you understand how RSLs work and how you
can most benefit from their use. The Flex compilers support static
linking and dynamic linking for class libraries (including RSLs).
Static linking is the most common type of linking when compiling
an application. However, dynamic linking lets you take advantage
of RSLs to achieve a reduction of the final SWF file size and, therefore,
a reduction in the application download time.</p>
<p>When you use <em>static linking</em>,
the compiler includes all referenced classes and their dependencies
in the application SWF file. The end result is a larger file that
takes longer to download than a dynamically-linked application,
but loads and runs quickly because all the code is in the SWF file. </p>
<p>To statically link a library's definitions into your application,
you use the <samp class="codeph">library-path</samp> and <samp class="codeph">include-libraries</samp> compiler
options to specify locations of SWC files. </p>
<p>When you use
the <samp class="codeph">library-path</samp> option, the compiler includes
only those classes required at compile time in the SWF file, so
the entire contents of a library are not necessarily compiled into
the SWF file. The <samp class="codeph">include-libraries</samp> option includes
the entire contents of the library, regardless of which classes
are required. You can also use the <samp class="codeph">source-path</samp> and <samp class="codeph">includes</samp> options
to embed individual classes in your SWF file.</p>
<p>If you statically link any part of a library into your application,
you cannot use that library as an RSL. </p>
<p>
<em>Dynamic linking</em> is when some classes
used by an application are left in an external file that is loaded
at run time. The result is a smaller SWF file size for the main
application, but the application relies on external files that are
loaded at run time. Dynamic linking is used by modules, runtime
stylesheets, and RSLs.</p>
<p>When you want to use a dynamically-linked library, you instruct
the compiler to exclude that library's contents from the application
SWF file when you compile the application. You must provide link-checking
at compile time even though the classes are not going to be included
in the final SWF file. At run time, the application loads the entire
library into the application SWF file, which can result in slower
startup times and greater memory usage. </p>
<p>You can use the <samp class="codeph">runtime-shared-library-path</samp> (Flex
4 and later) and <samp class="codeph">runtime-shared-libraries</samp> (Flex
3) options to specify the location of dynamically-linked libraries.</p>
<p>You can also use the <samp class="codeph">external-library-path</samp>, <samp class="codeph">externs</samp>,
or <samp class="codeph">load-externs</samp> compiler options to specify the
files to dynamically link into an application. These options instruct
the compiler to exclude classes and libraries from the application,
but to check links against them and prepare to load them at run time.
The <samp class="codeph">external-library-path</samp> option specifies SWC
files or directories for dynamic linking. The <samp class="codeph">externs</samp> option
specifies individual classes or symbols for dynamic linking. The <samp class="codeph">load-externs</samp> option
specifies an XML file that describes what classes to use for dynamic
linking. These options are most often used when externalizing assets
from modules so that the module and the application do not contain
overlapping class definitions. The <samp class="codeph">runtime-shared-library-path</samp> option
provides all the arguments to use external libraries as RSLs.</p>
<p>You can view the linking information for your application by
using the <samp class="codeph">link-report</samp> compiler option. This generates
a report that has the same syntax as the file that you load with
the <samp class="codeph">load-externs</samp> option, so you can use it as an argument
to that option without changing it. For more information about this report,
see <a href="flx_performance_pe.html#WS2db454920e96a9e51e63e3d11c0bf69084-7adc_verapache">Examining
linker dependencies</a>.</p>
<p>For more general information about the command-line compiler
options, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffd_verapache">Flex
compilers</a>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">RSL benefits</h3>
<div>
<p>The following
example shows the possible benefit of separating shared components
into an RSL. In this example, the library's size is 150 KB (kilobytes)
and the compiled application's size is 100 KB. Without RSLs, you
merge the library into both applications for an aggregate download
size of 500 KB. If you add a third or fourth application, the aggregate
download size increases by 250 KB for each additional application.</p>
<p>With RSLs, the RSL needs to be downloaded once only. For two
applications that use the same RSL, the result is an aggregate download
size of 350 KB, or a 30% reduction. If you add a third or fourth
application, the aggregate download size increases by 100 KB instead
of 250KB for each additional application. In this example, the benefits
of using an RSL increase with each new application. </p>
<div class="figborder">
<img src="images/rsl_benefits.png" alt="Comparison of an application\xd5 s size without RSLs and an application with RSLs."/>
</div>
<p>In this example, the applications with statically-linked libraries
run only after Adobe<sup>®</sup> Flash<sup>®</sup> Player
loads the 250 KB for each application. With dynamically linked RSLs,
however, only the first application must load the entire 250 KB
(the combined size of the application and the RSL). The second application
runs when just 100 KB loads because the RSL is cached.</p>
<p>The illustrated scenario shows one possible outcome. If your
applications do not use all of the components in the RSL, the size
difference (and, as a result, the savings in download time) might
not be as great. Suppose that each application only uses half of
the components in the RSL. If you statically link the library, only those
classes that are used are included; the output, as a result, is
100 KB + 75 KB for the first application and the library and 100
KB + 75 KB for the second application and the library, or an aggregate
download size of 350 KB. When you use a library as an RSL, its entire
SWF file must be transferred across the network and loaded by the
application at run time, regardless of how much of that library
is actually used. In this second case, the combined download size
when using RSLs and when not using RSLs is the same.</p>
<p>In general, the more applications that use a common RSL, the
greater the benefit.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">RSL considerations</h3>
<div>
<p>RSLs
are not necessarily beneficial for all applications. You should
try to test both the download time and startup time of your application
with and without RSLs.</p>
<p>Standard RSLs can not be shared across domains. If a client runs
an application in domain1.com and uses an RSL, and then launches
an application in domain2.com that uses the same RSL, the client
downloads the RSL twice even though the RSL is the same. You can
overcome this limitation of standard RSLs by using cross-domain
RSLs.</p>
<p>Cross-domain RSLs can be loaded by any application, even if that
application is not in the same domain. They do, however, require
that you create and check a digest when the RSL is loaded. This
can increase startup time of the application by a small amount.</p>
<p>Framework RSLs can also be loaded by any application. To take
advantage of the fact that framework RSLs can be cached in the Player
cache, the client must be running a recent version of Flash Player.
Not all clients necessarily have the latest Player, so loading a
framework RSL might fail. In these cases, you can specify a failover
RSL.</p>
<p>An RSL usually increases the startup time of an application.
This is because the entire library is loaded into an application
regardless of how much of the RSL is actually used. For this reason,
make your RSLs as small as possible. This contrasts with how statically-linked
libraries are used. When you compile an application, the compiler
extracts just the components it needs from those component libraries.</p>
<p>If you have several applications that share several libraries,
it might be tempting to merge the libraries into a single library
that you use as an RSL. However, if the individual applications
generally do not use more than one or two libraries each, the penalty
for having to load a single, large RSL might be higher than it would be
to have the applications load multiple smaller RSLs.</p>
<p>In this case, test your application with both a single large
RSL and multiple smaller RSLs, because the gains are largely application
specific. It might be better to build one RSL that has some extra
classes than to build two RSLs, if most users will load both of
them anyway.</p>
<p>If you have overlapping classes in multiple RSLs, be sure to
synchronize the versions so that the wrong class is never loaded.</p>
<p>You cannot use RSLs in ActionScript-only projects if the base
class is Sprite or MovieClip. RSLs require that the application's
base class, such as Application or SimpleApplication, understand
RSL loading.</p>
<p>In general, you should disable RSLs when compiling modules, CSS
SWF files, and applications that will be loaded as child SWFs in
a parent application. The parent application will likely use RSLs
and dynamically link the required classes.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">About caching</h3>
<div>
<p>RSLs are cached when they are first used. When they are
needed by another application, they can be loaded from the cache
rather than across the network. Caching is one of the benefits of
RSLs, because disk access is much faster than network access.</p>
<p>The type of caching used by an RSL is based on the type of RSL.
Standard or cross-domain RSLs are stored in the browser's cache.
If the user clears their cache, the RSLs are removed and must be
downloaded again the next time they are needed. Unsigned framework
RSLs are also stored in the browser's cache.</p>
<p>Signed framework RSLs are stored in the Player cache. This is
a special cache that is maintained by Flash Player. To clear this
cache, clients must invoke the Settings Manager. RSLs stored in
this cache are signed and therefore can be used by any application
without the need for a cross-domain policy file.</p>
<p>For more information about the framework cache, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ada_verapache">About
the Player cache</a>.</p>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481c-152c7c012d9aabe32a-8000_verapache"><a name="WS19f279b149e7481c-152c7c012d9aabe32a-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Common RSL tasks</h3>
<div>
<p>The techniques in this section apply to framework and custom
RSLs.</p>
</div>
<div class="nested3" id="WS19f279b149e7481c-152c7c012d9aabe32a-7fff_verapache"><a name="WS19f279b149e7481c-152c7c012d9aabe32a-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Removing unused RSLs</h4>
<div>
<p>By default, the compiler removes unused RSLs when an application
is compiled. This prevents an application from having to download
RSLs that it does not use. You can override this behavior by preventing
the compiler from removing unused RSLs.</p>
<p>To prevent unused RSLs from being removed, set the <samp class="codeph">remove-unused-rsls</samp> compiler
option to <samp class="codeph">false</samp>. The default value is <samp class="codeph">true</samp>.</p>
<div class="p">You can configure the <samp class="codeph">remove-unused-rsls</samp> compiler
option in the flex-config.xml file, as the following example shows:<pre class="codeblock">&lt;remove-unused-rsls&gt;true&lt;/remove-unused-rsls&gt;</pre>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-152c7c012d9aabe32a-7ffe_verapache"><a name="WS19f279b149e7481c-152c7c012d9aabe32a-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">Forcing RSLs to load</h4>
<div>
<p>You can force the compiler to load particular RSLs when
compiling your application. You do this with the <samp class="codeph">force-rsls</samp> compiler
option.</p>
<p>Forcing RSLs to load can be useful if you use classes that are
only referenced indirectly (sometimes referred to as "soft references"),
so the compiler might not know they are needed.</p>
<p>When forcing RSLs to load, you must configure them in the <samp class="codeph">runtime-shared-library-path</samp> option
in addition to specifying them with the <samp class="codeph">force-rsls</samp> option.</p>
<div class="p">The following example forces the osmf.swc and rpc.swc RSLs to
be loaded:<pre class="codeblock">mxmlc -force-rsls=libs/osmf.swc,libs/rpc.swc MyApp.mxml</pre>
</div>
<div class="p">You can configure the <samp class="codeph">force-rsls</samp> compiler option
in the flex-config.xml file, as the following example shows:<pre class="codeblock">&lt;runtime-shared-library-settings&gt;
&lt;force-rsls&gt;
&lt;path-element&gt;libs/osmf.swc&lt;/path-element&gt;
&lt;path-element&gt;libs/rpc.swc&lt;/path-element&gt;
&lt;/force-rsls&gt;
&lt;/runtime-shared-library-settings&gt;</pre>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-152c7c012d9aabe32a-7ffd_verapache"><a name="WS19f279b149e7481c-152c7c012d9aabe32a-7ffd_verapache"><!-- --></a>
<h4 class="topictitle4">Viewing required RSLs</h4>
<div>
<p>By default the compiler outputs a list of RSLs that an
application uses. This is viewable in the command line compiler's
output. </p>
<div class="p">The following is an example of the output from an application
that loads the framework, textLayout, spark, sparkskins, and osmf
RSLs:<pre class="codeblock">Required RSLs:
http://fpdownload.adobe.com/pub/swz/flex/4.6.0/framework_4.6.0.swf with 1 failover.
http://fpdownload.adobe.com/pub/swz/flex/4.6.0/textLayout_2.0.0.139.swf with 1 failover.
http://fpdownload.adobe.com/pub/swz/flex/4.6.0/spark_4.6.0.swf with 1 failover.
http://fpdownload.adobe.com/pub/swz/flex/4.6.0/osmf_1.0.0.16316.swf with 1 failover.</pre>
</div>
<p>The list of required RSLs displays the expected location of the
RSLs at runtime. In this case, the expected location is the signed
SWFs available on Adobe's website. The output also notes that there
is a failover location in case the Adobe RSLs are unavailable. You
can see this location in the flex-config.xml file.</p>
<p>Note that if <samp class="codeph">static-link-runtime-shared-libraries</samp> option
is set to <samp class="codeph">true</samp>, then no RSLs are listed because
they are not used. Static linking is used instead.</p>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-152c7c012d9aabe32a-7ffc_verapache"><a name="WS19f279b149e7481c-152c7c012d9aabe32a-7ffc_verapache"><!-- --></a>
<h4 class="topictitle4">Disabling RSLs</h4>
<div>
<p>You can disable RSLs when you compile your application
by setting the <samp class="codeph">static-link-runtime-shared-libraries</samp> compiler
option to <samp class="codeph">true</samp>.</p>
<p>In general, disabling RSLs is useful only when compiling style
SWF files, resource bundles, or other non-application assets.</p>
</div>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481c311d007d12d9f3bc5d8-8000_verapache"><a name="WS19f279b149e7481c311d007d12d9f3bc5d8-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Using RSLs with modules and sub-applications</h3>
<div>
<div class="p">RSLs are designed to work efficiently with modules and
sub-applications. When using RSLs with modules and sub-applications,
note that:<ul>
<li>
<p>Main applications only load RSLs that are needed,
but create placeholders for the remaining framework RSLs. This lets
the module or sub-application load other framework RSLs into the
main application when they need it.</p>
</li>
<li>
<p>Sub-applications and modules share framework RSLs by default. </p>
</li>
<li>
<p>Sub-applications and modules can share custom RSLs if you
configure the application domain that the RSLs are loaded into.</p>
</li>
</ul>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-64f4fc4712daa436650-8000_verapache"><a name="WS19f279b149e7481c-64f4fc4712daa436650-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Using placeholder RSLs</h4>
<div>
<p>When you compile an application with Flex, the default
behavior is to compile the application against the framework (or
default) RSLs. When the application runs, it loads only the framework
RSLs that it actually uses, and creates placeholders for the remaining
framework RSLs. When the application loads a module or sub-application
that requires one of the framework RSLs for which there is a placeholder,
the module or sub-application then loads that RSL into the main application.</p>
<p>If a module or sub-application requires a framework RSL that
is already loaded, it will not load the RSL again. It will instead
use the existing RSL.</p>
<p>To ensure that placeholders for framework RSLs are used, set
the <samp class="codeph">remove-unused-rsls</samp> compiler argument is <samp class="codeph">true</samp> when
compiling the main application, sub-applications, and modules. This
is the default.</p>
<p>By default, framework RSLs are loaded into the top-most application
domain that contains a placeholder for that RSL. As a result, modules
or sub-applications can share RSLs that were loaded by other modules
or sub-applications, as long as you do not restrict the domain into
which the RSL was loaded.</p>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-64f4fc4712daa436650-7fff_verapache"><a name="WS19f279b149e7481c-64f4fc4712daa436650-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Specifying domains for RSLs (advanced)</h4>
<div>
<p>When loading custom or framework RSLs into a sub-application
or module, you can specify the application domain into which the
RSL is loaded. You do this with the <samp class="codeph">application-domain</samp> compiler
argument. This lets you restrict RSLs from being shared, or ensure
that they are shared, among modules and sub-applications.</p>
<div class="p">The <samp class="codeph">application-domain</samp> compiler argument has
the following syntax:<pre class="codeblock">runtime-shared-library-settings.application-domain=
<em>path-element</em>,<em>application-domain-target</em></pre>
</div>
<p>The <samp class="codeph">path-element</samp> option specifies the location
of the RSL's SWC library file. This RSL must also be defined by
the <samp class="codeph">runtime-shared-library-path</samp> option.</p>
<div class="p">The <samp class="codeph">application-domain-target</samp> option takes one
the following values:<ul>
<li>
<p>
<samp class="codeph">default</samp> — Loads
the RSL into the top-most application domain with a placeholder.
If no placeholder is found, then the RSL is loaded into the current application
domain. </p>
</li>
<li>
<p>
<samp class="codeph">current</samp> — Loads the RSL into the module
or sub-application's current application domain. Modules and sub-applications
will not be able to share this RSL with anything other than child
modules or sub-applications.</p>
</li>
<li>
<p>
<samp class="codeph">top-level</samp> — Loads the RSL into the application
domain of the top-level SystemManager. This is the main or root
application. In this case, all modules and sub-applications will
be able to share this RSL.</p>
</li>
<li>
<p>
<samp class="codeph">parent</samp> — Loads the RSL into the application
domain of the parent application or module.</p>
</li>
</ul>
</div>
<div class="p">The following example snippet from the flex-config.xml file defines
a custom RSL, MyLibrary, and instructs it to be loaded into the
top-level application domain:<pre class="codeblock">&lt;runtime-shared-library-path&gt;
&lt;path-element&gt;libs/MyLibrary.swc&lt;/path-element&gt;
&lt;rsl-url&gt;bin/MyLibrary.swf&lt;/rsl-url&gt;
&lt;policy-file-url&gt;&lt;/policy-file-url&gt;
&lt;/runtime-shared-library-path&gt;
&lt;runtime-shared-library-settings&gt;
&lt;application-domain&gt;
&lt;path-element&gt;libs/MyLibrary.swc&lt;/path-element&gt;
&lt;application-domain-target&gt;top-level&lt;/application-domain-target&gt;
&lt;/application-domain&gt;
&lt;/runtime-shared-library-settings&gt;</pre>
</div>
<p>Note that RSLs can only be shared between sub-applications and
modules that have a common parent. A sub-application or module cannot
share RSLs with a sub-application that is untrusted (sandboxed)
or loaded for version compatibility (multi-versioned).</p>
<div class="section"><h5 class="sectiontitle">Preventing framework RSLs from being shared among
modules and sub-applications</h5>
<p>For framework RSLs, the default
is to load an RSL into the highest application domain that has a
placeholder for the RSL (typically the main application). The result
is that once a module or sub-application loads an RSL, all subsequent modules
or sub-applications that need this RSL will not have to load it.
The downside to this is that when the module or sub-application
is unloaded, the RSL is not unloaded.</p>
<p>To prevent a framework
RSL from being loaded into the main application, you can specify <samp class="codeph">"current"</samp> for
the application domain. This loads the RSL into the module or sub-application's
application domain. When the module or sub-application is unloaded,
so is the RSL. Other modules or sub-applications will not have access
to it. You should not specify <samp class="codeph">"current"</samp> for the
application domain when loading the OSMF or MX RSLs. These RSLs
are always loaded into the root application.</p>
</div>
<div class="section"><h5 class="sectiontitle">Sharing custom RSLs among modules and sub-applications</h5>
<p>For
custom RSLs, the default is to load the RSL into the module or sub-application's
current application domain. The result is that the module or sub-application
does not share the RSL with sibling modules or sub-applications,
but only with child sub-applications or modules that it loads.</p>
<p>To
load a custom RSL into an application domain so that it can then
be shared with other modules and sub-applications, you specify <samp class="codeph">"top-level"</samp> for
the application domain. This loads the custom RSL into the main
application. All modules and sub-applications will then be able
to access that RSL.</p>
<p>You should ensure that applications or
modules do not statically link classes in a custom RSL. If those
classes are loaded before the RSL is loaded, then class conflicts
can occur when the RSL is loaded. One technique to use when doing
this is to ensure that all modules, sub-applications, and the main
application share the same RSL definitions. If this is the case,
classes will not be statically linked when they exist in an RSL.</p>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache"><!-- --></a>
<h2 class="topictitle2">Using the framework RSLs</h2>
<div>
<p>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.</p>
<p>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.</p>
<div class="p">Framework RSLs come in two versions: signed and unsigned.<ul>
<li>
<p>
<em>Signed framework RSLs</em> 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.</p>
</li>
<li>
<p>
<em>Unsigned framework RSLs</em> 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.</p>
</li>
</ul>
</div>
<p>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.</p>
<p>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. </p>
<p>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.)</p>
<p>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.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe9_verapache"><!-- --></a><h3 class="sectiontitle">Included
framework RSLs</h3>
<p>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.</p>
<div class="p">The
framework RSLs that are included in the SDK installation are located
in the <em>flex_sdk_dir</em>/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:
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e787">
<p>File Name</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e793">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>charts<em>_version.build</em>.swf</p>
<p>charts<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing charting
classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>framework<em>_version.build</em>.swf</p>
<p>framework<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing framework
classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>mx<em>_version.build</em>.swf</p>
<p>mx<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing MX components
and supporting classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>osmf<em>_version.build</em>.swf</p>
<p>osmf<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing OSMF-related
classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>rpc<em>_version.build</em>.swf</p>
<p>rpc<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing data
services classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>spark<em>_version.build</em>.swf</p>
<p>spark<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing Spark
components and supporting classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>spark_dmv<em>_version.build</em>.swf</p>
<p>spark_dmv<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing Spark
classes used by the AdvancedDataGrid and OLAPDataGrid classes.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>sparkskins<em>_version.build</em>.swf</p>
<p>sparkskins<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing Spark
skins classes for MX components.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e787 ">
<p>textLayout<em>_version.build</em>.swf</p>
<p>textLayout<em>_version.build</em>.swz</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e793 ">
<p>Signed and unsigned RSLs containing TLF-related
classes.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p>The SWZ and SWF files are files that
you deploy. The SWC files in the framework/libs directory are the
files that you compile your application against. </p>
<p>The signed
framework RSLs are optimized, as described in <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache">Optimizing
RSL SWF files</a>. This means that they do not include debugging
information. If you compile on the command line 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. </p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe7_verapache"><!-- --></a><h3 class="sectiontitle">Configuring
framework RSLs</h3>
<p>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.</p>
<p>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.</p>
<p>The following example shows an entry in
the configuration file that loads one of the framework RSLs:</p>
<pre class="codeblock">&lt;runtime-shared-library-path&gt;
&lt;path-element&gt;libs/framework.swc&lt;/path-element&gt;
&lt;rsl-url&gt;${hosted.rsl.url}/flex/${build.number}/framework_${build.number}.swz&lt;/rsl-url&gt;
&lt;policy-file-url&gt;${hosted.rsl.url}/crossdomain.xml&lt;/policy-file-url&gt;
&lt;rsl-url&gt;framework_${build.number}.swz&lt;/rsl-url&gt;
&lt;policy-file-url&gt;&lt;/policy-file-url&gt;
&lt;/runtime-shared-library-path&gt;</pre>
<p>The configuration
file uses a <samp class="codeph">{hosted.rsl.url}</samp> token in the first <samp class="codeph">&lt;rsl-url&gt;</samp> 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 <samp class="codeph">&lt;rsl-url&gt;</samp> element in the list. In
this case, it is the SWZ file in the same directory as the application.</p>
<p>The
configuration file also uses a <samp class="codeph">{build.number}</samp> 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.</p>
<p>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 <samp class="codeph">runtime-shared-library-path</samp> 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. </p>
<p>The
following example compiles SimpleApp with the framework RSL:</p>
<pre class="codeblock"> mxmlc -runtime-shared-library-path=libs/framework.swc,
  framework_4.6.0.swz,,framework_4.6.0.swf
  SimpleApp.mxml</pre>
<p>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.</p>
<p>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. </p>
<p>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 <a href="flx_wrapper_wr.html#WSDF4E56EF-2198-4843-ACF0-D78D52422046_verapache">Using
Express Install in the wrapper</a>. (Flex 4 applications require
Player 10.0 or later, so this might not be an issue for you.)</p>
<p>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.</p>
</div>
<div class="section"><h3 class="sectiontitle">Disabling framework RSLs</h3>
<div class="p">The use of framework
RSLs is enabled by default. You can disable RSLs when you compile
your application by setting the <samp class="codeph">static-link-runtime-shared-libraries</samp> compiler
option to <samp class="codeph">true</samp>, as the following example shows:<pre class="codeblock">mxmlc -static-link-runtime-shared-libraries=true MyApp.mxml</pre>
</div>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7fe8_verapache"><!-- --></a><h3 class="sectiontitle">Framework
RSL digests</h3>
<p>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. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ada_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ada_verapache"><!-- --></a>
<h3 class="topictitle3">About the Player cache</h3>
<div>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The following table shows the locations of the Player cache on
various platforms:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1171">
<p>Platform</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1177">
<p>Location</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1171 ">
<p>Windows 95/98/ME/2000/XP</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1177 ">
<p>C:\Documents and Settings\<em>user_name</em>\Application
Data\Adobe\Flash Player\AssetCache\</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1171 ">
<p>Windows Vista</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1177 ">
<p>C:\Users\<em>user_name</em>\AppData\Roaming\Adobe\Flash
Player\AssetCache\</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1171 ">
<p>Linux</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1177 ">
<p>/home/<em>user_name</em>/.adobe/Flash_Player/AssetCache/</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1171 ">
<p>Mac OSX</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1177 ">
<p>/Users/<em>user_name</em>/Library/Cache/Adobe/Flash
Player/AssetCache/</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fe1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fe1_verapache"><!-- --></a>
<h3 class="topictitle3">Example of using the framework
RSLs on the command line</h3>
<div>
<p>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.</p>
<p>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. </p>
<p>Compile the application as you normally would, with one exception.
Add the <samp class="codeph">static-link-runtime-shared-libraries=true</samp> 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.</p>
<p>With the mxmlc command-line compiler, use the following command
to compile the application:</p>
<pre class="codeblock"> mxmlc -static-link-runtime-shared-libraries=true bin/SimpleApp.mxml</pre>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<pre class="codeblock"> 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</pre>
<p>The result is a SWF file that should be smaller than the previous
SWF file.</p>
<p>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. </p>
<p>In addition, the <samp class="codeph">runtime-shared-library-path</samp> 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.</p>
<p>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. </p>
<div class="p">
<div class="note"><span class="notetitle">Note:</span> 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.</div>
</div>
<p>Request the application in the browser or create a wrapper for
the application and request that file.</p>
<p>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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ada_verapache">About the
Player cache</a>.</p>
<p>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.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7ff6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7ff6_verapache"><!-- --></a>
<h2 class="topictitle2">Using standard and cross-domain
RSLs</h2>
<div>
<p>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.</p>
<p>To use standard or cross-domain RSLs, you perform the following
tasks:</p>
<dl>
<dt class="dlterm">Create a library</dt>
<dd>
<p>An RSL is created from a library of custom classes and other assets.
You create a library with 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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache">Creating
libraries</a>.</p>
</dd>
<dt class="dlterm">Compile your application against the library</dt>
<dd>
<p>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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad7_verapache">Compiling
applications with standard and cross-domain RSLs</a>.</p>
</dd>
<dt class="dlterm">Optimize the RSL</dt>
<dd>
<p>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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache">Optimizing
RSL SWF files</a>.</p>
</dd>
<dt class="dlterm">Deploy the RSL</dt>
<dd>
<p>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.</p>
</dd>
</dl>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7adf_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7adf_verapache"><!-- --></a>
<h3 class="topictitle3">About standard RSLs</h3>
<div>
<p>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:</p>
<ul>
<li>
<p>You
host multiple applications in the same domain.</p>
</li>
<li>
<p>You have custom component libraries.</p>
</li>
<li>
<p>More than one application uses those custom component libraries.</p>
</li>
</ul>
<p>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.</p>
<p>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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad2_verapache">About
RSL digests</a>.</p>
<p>The following is a list of typical applications that can benefit
from standard RSLs:</p>
<ul>
<li>
<p>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.</p>
</li>
<li>
<p>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).</p>
</li>
<li>
<p>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.</p>
</li>
</ul>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ae0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ae0_verapache"><!-- --></a>
<h3 class="topictitle3">About cross-domain RSLs</h3>
<div>
<p>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.</p>
<p>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:</p>
<pre class="codeblock"> &lt;cross-domain-policy&gt;
  &lt;site-control permitted-cross-domain-policies="all"/&gt;
  &lt;allow-access-from domain="*" to-ports="*"/&gt;
 &lt;/cross-domain-policy&gt;</pre>
<p>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 <samp class="codeph">domain</samp> attribute.
You should also consider using a more restrictive meta-policy with
the <samp class="codeph">permitted-cross-domain-policies</samp> attribute.
For more information, see <a href="flx_security2_se.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f2b_verapache">Using
cross-domain policy files</a>.</p>
<p>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.</p>
<p>Cross-domain RSLs can fail to load into an application under
the following conditions:</p>
<ul>
<li>
<p>The server on which the RSL is located fails</p>
</li>
<li>
<p>The network fails, so remote files cannot be loaded</p>
</li>
<li>
<p>The digest of the RSL when the application was compiled does
not match the digest of the RSL when it is loaded</p>
</li>
<li>
<p>The policy file is absent from the RSL's server, or that
server has a restrictive meta-policy</p>
</li>
</ul>
<p>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.</p>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad2_verapache"><!-- --></a>
<h4 class="topictitle4">About RSL digests</h4>
<div>
<p>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 <em>digest</em>. 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.</p>
<p>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. </p>
<p>To create a digest while compiling a library, you set the <samp class="codeph">compute-digest</samp> compiler
option to <samp class="codeph">true</samp>. You can set this value in the flex-config.xml
file, as the following example shows:</p>
<pre class="codeblock"> &lt;compute-digest&gt;true&lt;/compute-digest&gt;</pre>
<p>The default value of the <samp class="codeph">compute-digest</samp> option
is <samp class="codeph">true</samp>. </p>
<p>The compiler writes the digest inside the <samp class="codeph">swc/libraries/library/digests</samp> element
of the RSL's catalog.xml file. The following example shows the structure
of <samp class="codeph">digest</samp> elements, which are optional children
of the <samp class="codeph">digests</samp> element in the catalog.xml file: </p>
<pre class="codeblock"> &lt;digests&gt;
  &lt;digest type="SHA-256" signed="true"
value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"/&gt;
  &lt;digest type="SHA-256" signed="false"
value="d604d909d8d6d358097cf2f4ebf4707faf330469ed6b41dcdc5aaf6f4dd3bea9"/&gt;
 &lt;/digests&gt;</pre>
<p>The following table describes the tag and its attributes:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1651">
<p>Option</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1657">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1651 ">
<div class="p">
<pre class="codeblock">digest</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1657 ">
<p>Optional child of <samp class="codeph">digests</samp> element. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1651 ">
<div class="p">
<pre class="codeblock">signed</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1657 ">
<p>Whether the library is signed or not. This
value is <samp class="codeph">true</samp> if the digest is of a signed library
and <samp class="codeph">false</samp> otherwise. Only Adobe can create signed
libraries. This attribute is required.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1651 ">
<div class="p">
<pre class="codeblock">type</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1657 ">
<p>The kind of hash used to create the digest.
The only currently-supported value is "SHA-256". This attribute
is required.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1651 ">
<div class="p">
<pre class="codeblock">value</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1657 ">
<p>The hash of the specified type. This is
the digest of the RSL associated with the catalog.xml. This attribute
is required.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>When you compile your production application with an RSL that
uses a digest for verification, set the <samp class="codeph">verify-digests</samp> compiler
option to <samp class="codeph">true</samp> to indicate that the application
must check the digest before using the RSL. The default value of this
option is <samp class="codeph">true</samp>.</p>
<p>If you have multiple RSLs, such as a main RSL plus a failover
RSL, the compiler stores multiple digests inside the application.</p>
<p>The Flex compiler uses the SHA-256 digest algorithm from the
java.security libraries to generate the digest.</p>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7ff2_verapache"><!-- --></a>
<h4 class="topictitle4">About failover</h4>
<div>
<p>The failover feature is used for two reasons:</p>
<ul>
<li>
<p>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.)</p>
</li>
<li>
<p>If a network or server failure occurs while loading the main
RSL, Flash Player will attempt to load the failover RSL.</p>
</li>
</ul>
<p>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. </p>
<p>For all RSLs, the failover RSL provides a mechanism to load an
RSL if the primary server is unavailable.</p>
<p>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 <samp class="codeph">runtime-shared-library-path</samp> option. The default
failover RSL is framework_4.0.${build.number}.swf. </p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad7_verapache"><!-- --></a>
<h3 class="topictitle3">Compiling applications with standard
and cross-domain RSLs</h3>
<div>
<p>To compile your application with standard or cross-domain
RSLs you must extract the RSL SWF 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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache">Optimizing
RSL SWF files</a>.</p>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fef_verapache"><!-- --></a>
<h4 class="topictitle4">Compile with standard or cross-domain
RSLs on the command line</h4>
<div>
<p>To use standard or cross-domain RSLs in your application
on the command line, you use the <samp class="codeph">runtime-shared-library-path</samp> application
compiler option. This option has the following syntax:</p>
<pre class="codeblock"> -runtime-shared-library-path=<em>path-element</em>,<em>rsl-url</em>[,<em>policy-file-url</em>,<em>failover-url</em>,...]</pre>
<p>The following table describes the <samp class="codeph">runtime-shared-library-path</samp> arguments:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1889">
<p>Argument</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e1895">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1889 ">
<div class="p">
<pre class="codeblock">path-element</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1895 ">
<p>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. </p>
<p>This argument is required.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1889 ">
<div class="p">
<pre class="codeblock">rsl-url</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1895 ">
<p>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 <em>web_root</em>/libraries
directory on the web server, and the application in the web root,
you specify libraries/library.swf for the RSL SWF file. </p>
<p>This
argument is required.</p>
<p>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.</p>
<p>The value of the <samp class="codeph">rsl-url</samp> 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.</p>
<p>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 <samp class="codeph">rsl-url</samp> option.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1889 ">
<div class="p">
<pre class="codeblock">policy-file-url</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1895 ">
<p>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. </p>
<p>This argument is optional. </p>
<p>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 <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ae0_verapache">About
cross-domain RSLs</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1889 ">
<div class="p">
<pre class="codeblock">failover-url</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e1895 ">
<p>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.)</p>
<p>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. </p>
<p>This argument is optional. </p>
<p>If
you specify a second <samp class="codeph">policy-file-url</samp>, then Flash
Player will look to that location for the crossdomain.xml file for
the failover RSL. </p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example shows how to use the <samp class="codeph">runtime-shared-library-path</samp> option
when compiling your application on the command line:</p>
<pre class="codeblock"> mxmlc -runtime-shared-library-path=../lib/mylib.swc,../bin/library.swf Main.mxml</pre>
<p>Do not include spaces between the comma-separated arguments of
the <samp class="codeph">runtime-shared-library-path</samp> option on the command
line. </p>
<p>Your application can use any number of RSLs. IWhen using the
command line, you add additional <samp class="codeph">runtime-shared-library-path</samp> options.
In both cases, the order of the RSLs is significant because base
classes must be loaded before the classes that use them.</p>
<p>You can also use a configuration file to use RSLs, as the following
example shows:</p>
<pre class="codeblock"> &lt;runtime-shared-library-path&gt;
  &lt;path-element&gt;../lib/mylib.swc&lt;/path-element&gt;
  &lt;rsl-url&gt;../bin/library.swf&lt;/rsl-url&gt;
 &lt;/runtime-shared-library-path&gt;</pre>
<p>In the previous example, the file structure at compile time looks
like this:</p>
<pre class="codeblock"> c:/Main.mxml
 c:/lib/CustomDataGrid.swc</pre>
<p>The deployed files are structured like this:</p>
<pre class="codeblock"> <em>web_root</em>/Main.swf
 <em>web_root</em>/bin/library.swf</pre>
<p>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:</p>
<pre class="codeblock"> 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</pre>
<p>In the configuration file, this would be represented as follows:</p>
<pre class="codeblock"> &lt;runtime-shared-library-path&gt;
  &lt;path-element&gt;../lib/mylib.swc&lt;/path-element&gt;
  &lt;rsl-url&gt;http://www.my-domain.com/rsls/library.swf&lt;/rsl-url&gt;
  &lt;policy-file-url&gt;http://www.my-domain.com/rsls/crossdomain.xml&lt;/rsl-url&gt;
  &lt;rsl-url&gt;http://www.my-other-domain.com/rsls/library.swf&lt;/rsl-url&gt;
  &lt;policy-file-url&gt;http://www.my-other-domain.com/rsls/crossdomain.xml&lt;/rsl-url&gt;
 &lt;/runtime-shared-library-path&gt;</pre>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fee_verapache"><!-- --></a>
<h4 class="topictitle4">Toggling RSLs on the command line</h4>
<div>
<p>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.</p>
<p>To enable the use of RSLs without editing the configuration file,
set the value of <samp class="codeph">static-link-runtime-shared-libraries</samp> to <samp class="codeph">false</samp>.
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 <samp class="codeph">true</samp>. </p>
<p>While you typically set the value of the <samp class="codeph">static-link-runtime-shared-libraries</samp> 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 <samp class="codeph">static-link-runtime-shared-libraries</samp> option
in the configuration file is ignored.</p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache"><!-- --></a>
<h3 class="topictitle3">Optimizing RSL SWF files</h3>
<div>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>The syntax for the optimizer tool is as follows:</p>
<pre class="codeblock"> optimizer -keep-as3-metadata Bindable Managed ChangeEvent  NonCommittingChangeEvent Transient -input <em>input_swf</em> -output <em>output_swf</em></pre>
<p>You must specify the <samp class="codeph">keep-as3-metadata</samp> 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.</p>
<p>You can specify the configuration file that the optimizer tool
uses by using the <samp class="codeph">load-config</samp> option.</p>
<p>To get help while using the optimizer tool, enter the <samp class="codeph">-help list advanced</samp> option:</p>
<pre class="codeblock">optimizer -help list advanced</pre>
<p>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.</p>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fec_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fec_verapache"><!-- --></a>
<h4 class="topictitle4">Use optimized RSLs</h4>
<div>
<ol>
<li>
<p>Create an RSL by building a SWC file with the compc
command line tool.</p>
</li>
<li>
<p>Compile your main application and reference the RSL.</p>
</li>
<li>
<p>Extract the library.swf file from your RSL's SWC file, if
you haven't done so already.</p>
</li>
<li>
<p>Run the optimizer against the library.swf file, for example:</p>
<pre class="codeblock">optimizer -keep-as3-metadata Bindable Managed ChangeEvent  NonCommittingChangeEvent Transient -input c:\rsls\library.swf -output c:\rsls\output\output.swf</pre>
</li>
<li>
<div class="p">Run the digest tool against the optimized library.swf file;
for example:<pre class="codeblock">digest -digest.rsl-file c:\rsls\output\output.swf -digest.swc-path c:\rsls\output\</pre>
</div>
</li>
<li>
<p>Deploy the optimized library (in this case, output.swf) with
the application so that the application uses it at run time.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7feb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7feb_verapache"><!-- --></a>
<h3 class="topictitle3">Example of creating and using a
standard and cross-domain RSL</h3>
<div>
<p>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 first shows you how to use a standard RSL, and then how to use
that same RSL as a cross-domain RSL.</p>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<pre class="codeblock"> project/src/app.mxml
 project/libsrc/ProductConfigurator.as
 project/libsrc/ProductView.as
 project/lib/
 project/bin/</pre>
<p>To compile this application without using libraries, you can
link the classes in the /libsrc directory using the <samp class="codeph">source-path</samp> option,
as the following example shows:</p>
<pre class="codeblock"> cd project/src
 mxmlc -o=../bin/app.swf -source-path+=../libsrc app.mxml</pre>
<p>This command adds the ProductConfigurator and ProductView classes
to the SWF file. </p>
<p>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:</p>
<pre class="codeblock"> cd project
 compc -source-path+=libsrc -debug=false -o=lib/mylib.swc ProductConfigurator ProductView</pre>
<p>This compiles the mylib.swc file in the lib directory. This SWC
file contains the implementations of the ProductConfigurator and
ProductView classes. </p>
<p>To recompile your application with the new library, you add the
library with the <samp class="codeph">library-path</samp> option, as the following
example shows:</p>
<pre class="codeblock"> cd project/src
 mxmlc -o=../bin/app.swf -library-path+=../lib/mylib.swc app.mxml</pre>
<p>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.</p>
<p>Now you can recompile the application to use the library as an
external RSL rather than as a library linked at compile time. </p>
<p>The first step is to compile your application with the <samp class="codeph">runtime-shared-library-path</samp> 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.</p>
<pre class="codeblock"> cd project/src
 mxmlc -o=../bin/app.swf -runtime-shared-library-path=../lib/mylib.swc,myrsl.swf app.mxml</pre>
<p>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. </p>
<p>The following example extracts the SWF file by using the unzip
utility on the command line:</p>
<pre class="codeblock"> cd project/lib
 unzip mylib.swc library.swf
 mv library.swf ../bin/myrsl.swf</pre>
<p>This example renames the library.swf file to myrsl.swf and moves
it to the same directory as the application SWF file.</p>
<p>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:</p>
<pre class="codeblock"> optimimzer -keep-as3-metadata Bindable Managed ChangeEvent NonCommittingChangeEvent Transient
-input bin/myrsl.swf -output bin/myrsl.swf</pre>
<p>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 <samp class="codeph">runtime-shared-library-path</samp> option. </p>
<p>You can optionally run the optimizer tool on the myrsl.swf file
to make it smaller before deploying it. For more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache">Optimizing
RSL SWF files</a>.</p>
<p>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:</p>
<pre class="codeblock"> 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</pre>
<p>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:</p>
<pre class="codeblock"> &lt;cross-domain-policy&gt;
  &lt;site-control permitted-cross-domain-policies="all"/&gt;
  &lt;allow-access-from domain="*.my-local-domain.com" to-ports="*"/&gt;
 &lt;/cross-domain-policy&gt;</pre>
<p>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.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache"><!-- --></a>
<h2 class="topictitle2">Creating libraries</h2>
<div>
<p>To use standard or cross-domain RSLs, you must first create
the library that will be used as an RSL. If you want to use framework
RSLs, the libraries are already created for you. In that case, all
you need to do is compile against them and then deploy the SWZ or
SWF file with your application.</p>
<p>A
standard or cross-domain RSL is a library of custom components,
classes, and other assets that you create. You can create a library
using the compc command-line compiler. A library is a SWC file or
open directory that contains a library.swf file and a catalog.xml
file, as well as properties files and other embedded assets. You
can use any library as an RSL, but libraries do not need to be used
as RSLs. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7ff8_verapache"><!-- --></a><h3 class="sectiontitle">Creating
libraries on the command line</h3>
<p>On the command line, you create a library
by using the compc compiler. You add files to a library by using
the <samp class="codeph">include-classes</samp> and <samp class="codeph">include-namespaces</samp> options
when you compile the SWC file.</p>
<p>The following example creates
a library called CustomCellRenderer.swc with the compc compiler:</p>
<pre class="codeblock"> compc -source-path ../mycomponents/components/local
  -include-classes CustomCellRendererComponent
  -directory=true
  -debug=false
  -output ../libraries/CustomCellRenderer</pre>
<p>The options
on the command line can also be represented by settings in the flex-config.xml
file, as the following example shows:</p>
<pre class="codeblock"> &lt;?xml version="1.0"&gt;
 &lt;flex-config&gt;
  &lt;compiler&gt;
  &lt;source-path&gt;
  &lt;path-element&gt;../mycomponents/components/local&lt;/path-element&gt;
  &lt;/source-path&gt;
  &lt;/compiler&gt;
  &lt;output&gt;../libraries/CustomCellRenderer&lt;/output&gt;
  &lt;directory&gt;true&lt;/directory&gt;
  &lt;debug&gt;false&lt;/false&gt;
  &lt;include-classes&gt;
  &lt;class&gt;CustomCellRendererComponent&lt;/class&gt;
  &lt;/include-classes&gt;
 &lt;/flex-config&gt;</pre>
<p>All classes and components must
be statically linked into the resulting library. When you use the
compc compiler to create the library, do not use the <samp class="codeph">include-file</samp> option
to add files to the library, because this option does not statically
link files into the library.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7ff7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7ad5_verapache__WS2db454920e96a9e51e63e3d11c0bf674ba-7ff7_verapache"><!-- --></a><h3 class="sectiontitle">Optimizing
libraries</h3>
<p>Optimizing libraries means to remove debugging
and other code from the library prior to deployment. For normal
libraries that you are not using as RSLs, you do not need to optimize.
This is because you will likely want to debug against the library
during development, so you will need the debug code inside the library.
And, when you compile the release version of your application, the compiler
will exclude debug information as it links the classes from the
library.</p>
<p>When you compile a library for production use as
an RSL, however, you can set the <samp class="codeph">debug</samp> compiler
option to <samp class="codeph">false</samp>. The default value is <samp class="codeph">true</samp> for
compc, which means that the compiler, by default, includes extra
information in the SWC file to make it debuggable. You should avoid
creating a debuggable library that you intend to use in production
so that the RSL's files are as small as possible. If you set the
value of the <samp class="codeph">debug</samp> option to <samp class="codeph">false</samp>,
however, you will not be able to debug against the RSL for testing. </p>
<p>If
you do include debugging information, you can still optimize the
RSL after compiling it, which removes the debugging information
as well as unnecessary metadata. For more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad9_verapache">Optimizing
RSL SWF files</a>.</p>
<p>Before you deploy an RSL, you extract
the SWF file that is inside the library SWC file and optimize it.
The default name of this SWF file is library.swf. After you extract
it from the SWC file, you can rename it to anything you want. When
you deploy the RSL, you deploy the SWF file so that the application
can load it at run time. </p>
<p>On the command line, you typically
specify that the output of compiling a library be an open directory
rather than a SWC file by using the <samp class="codeph">directory</samp> option
and the <samp class="codeph">output</samp> option. The output is an open directory
that contains the following files:</p>
<ul>
<li>
<p>catalog.xml</p>
</li>
<li>
<p>library.swf</p>
</li>
</ul>
<p>In addition, the library contains
properties files and any images or other embedded assets that are
used by the library.</p>
<p>If you do not specify that the output
be an open directory, you must manually extract the library.swf
file from the SWC file with a compression utility, such as PKZip.</p>
<p>You
specify the deployment location of the SWF file when you add the
SWC file to your project as an RSL.</p>
<p>When creating a library,
you need to know if you will be using the library as a standard
RSL or as a cross-domain RSL. If you are using it as a cross-domain
RSL, you must include the digest information in the library. For
more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ae0_verapache">About
cross-domain RSLs</a>.</p>
<p>After you create the library, you
then compile your application against the SWC file and specify the
library's SWF file's location for use at run time. For more information,
see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ad7_verapache">Compiling
applications with standard and cross-domain RSLs</a>.</p>
<p>For
more information on using the compc compiler options, see <a href="flx_compilers_cpl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ffd_verapache">Flex
compilers</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf674ba-7fe0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf674ba-7fe0_verapache"><!-- --></a>
<h2 class="topictitle2">Troubleshooting RSLs</h2>
<div>
<p>RSLs can be complicated to create, use, and deploy. The
following table describes common errors and techniques to resolve
them:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e2559">
<p>Error</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d840925e2565">
<p>Resolution</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">#1001 Digest mismatch with RSL</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>This error indicates that the digest of
a library does not match the RSL SWF file. When you compile an application
that uses an RSL, you specify the library SWC file that the application
uses for link checking at compile time and an RSL SWF file that
the application loads at run time. The digest in the library's catalog.xml
file must match the digest of the RSL SWF file or you will get this
error. If this error persists, recompile the application against
the library SWC file again and redeploy the application's SWF file.</p>
<p>If
you are using framework RSLs, then the SWZ file is a different version
than what the application was compiled against. Check whether this
is the case by adding a failover RSL SWF file and recompiling. If
the error does not recur, then the SWZ file is out of sync.</p>
<p>If
you are creating an optimized RSL, be sure to run the digest tool
against the library.swf file after you optimized the library.swf
file.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">#2032</pre>
Stream
Error</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>This error indicates that the SWZ or SWF
file is not being found. </p>
<p>The frequently occurs if the client
is not able to download the signed framework RSL from the Adobe
web site, and you have not deployed a local signed framework RSL.
If the client has limited or not internet connectivity, be sure
to deploy the local framework RSL to a location that is accessible
to the client. For more information, see <a href="flx_rsl_rsl.html#WS2db454920e96a9e51e63e3d11c0bf69084-7add_verapache">Using
the framework RSLs</a>.</p>
<p>It can also occur if Flash Player
tries to load a custom RSL that is not available. For example, if
you specified only "mylib.swf" as the value of the <samp class="codeph">rsl-url</samp> parameter
to the <samp class="codeph">runtime-shared-library-path</samp> option, but
the SWF file is actually in a sub-directory such as /rsls, then
you must either recompile your application and update the value
of the <samp class="codeph">rsl-url</samp> parameter to "rsls/mylib.swf", or
move mylib.swf to the same directory as the application's SWF file.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">#2046</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>This error indicates that the loaded RSL
was not signed properly. In the case of framework RSLs, the framework's
SWZ file that the application attempted to load at run time was
not a properly signed SWZ file. You must ensure that you deploy
an Adobe-signed RSL, or be sure to use the signed framework RSLs
that are deployed on the Adobe web site.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">#2048</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>The cause of this error is that you do not
have a crossdomain.xml file on the server that is returning the
RSL. You should add a file to that server. For more information,
see <a href="flx_security2_se.html#WS2db454920e96a9e51e63e3d11c0bf69084-7f2b_verapache">Using
cross-domain policy files</a>.</p>
<p>If you are loading signed
framework RSLs from the Adobe web site, you should not get this
error.</p>
<p>If you put the crossdomain.xml file at the server's
root, you do not have to recompile your application. This is because
the application will look for that file at the server's root by
default, so there is no need to explicitly define its location. </p>
<p>If
you cannot store a crossdomain.xml file at the remote server's root,
but can put it in another location on that server, you must specify
the file's location when you compile the application. On the command
line, you do this by setting the value of the <samp class="codeph">policy-file-url</samp> argument
of the <samp class="codeph">runtime-shared-library-path</samp> option.</p>
<p>In
the following example, the RSL SWF file is located in the /rsls
directory on www.domain.com. The crossdomain.xml file is located
in the same directory, which is not the server's root, so it must
therefore be explicitly specified:</p>
<div class="p">
<pre class="codeblock">mxmlc -runtime-shared-library-path= ../lib/mylib.swc, http://www.mydomain.com/rsls/myrsl.swf, http://www.mydomain.com/rsls/crossdomain.xml Main.mxml</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">#2148</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>This error occurs when you try to open an
application that uses RSLs in the standalone player or in the browser
by using the file system and not a server. It means that you are
violating the security sandbox of Flash Player by trying to load
file resources.</p>
<p>You must deploy your application and RSLs
to a network location, and request the application with a network
request so that Flash Player will load the RSL.</p>
<p>If you are
testing the application locally, you can add the directory to your
Player trust file to avoid this error.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2559 ">
<div class="p">
<pre class="codeblock">Requested resource not found</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d840925e2565 ">
<p>You might find this error in your web server
logs. If you deploy the RSL SWF file to a location other than that specified
when you compiled the application, then you will get an error similar
to this when the application tries to run.</p>
<p>The solution is
to either recompile your application and correct the deployment
location of the RSL SWF file or to move the RSL SWF file to the
location that the application expects.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p/>
</div>
<div>
<p><strong>Navigation</strong></p>
<p><a href="index.html">Using Flex</a> &raquo; <a href="flx_p2_app_architecture.html">Application architecture</a></p>
</div>
<p>Adobe and Adobe Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>