The release notes provide information about a release, including descriptions of significant new features and changes, instructions for upgrading from an earlier release, and important platform-specific details.

On this page:

Supported Platforms for Ice for ActionScript 1.0b

Ice for ActionScript supports the following run-time environments:

• Adobe AIR 2 and AIR 3
• Adobe Flash Player 10 and Flash Player 11

Ice for ActionScript supports the following development environments:

• Adobe Flash Builder 4.5.1
• Flex SDK 4.5.1

Supported Features for Ice for ActionScript 1.0b

Ice for ActionScript does not support the entire set of Ice features that are found in the C++, Java, and C# language mappings, primarily due to platform and API limitations. Furthermore, some Ice for ActionScript features require AIR and are not available when using Flash.

The table below provides more details on the Ice for ActionScript feature set:

Feature	AIR	Flash	Notes
Synchronous invocations			ActionScript's single-threaded nature makes synchronous invocations impractical.
Asynchronous invocations
Synchronous dispatch
Asynchronous dispatch
Outgoing TCP connections			Flash uses policy files to validate outgoing socket connections.
Incoming TCP connections			Flash programs must use bidirectional connections to receive callbacks. AIR programs can also be Ice servers.
Outgoing SSL connections			ActionScript's SSL implementation has some limitations. SSL is supported in Flash 11 but not in Flash 10.
Incoming SSL connections
Datagrams
DNS queries			The lack of support for DNS queries in Flash affects fault tolerance.
File logging
Property files
Flow control API			The socket API provides no indication when a packet has been sent.
Thread pools			Threads are not supported in ActionScript.
PerThread implicit context			Threads are not supported in ActionScript.
Protocol compression			Ice uses the bzip2 algorithm, which is not natively supported in ActionScript.
Communicator plug-ins
Dispatcher API
DispatchInterceptor API
Collocated invocations
Streaming API

SSL limitations

Support for SSL in Ice for ActionScript is affected by several limitations:

• SSL is not supported in Flash 10
• SSL is only available for outgoing connections
• No APIs are provided for configuring the SSL connection, such as supplying a client certificate or selecting certain ciphersuites
• Adobe's SSL implementation performs very strict authentication: the server must supply a valid, non-expired certificate, and the host name in the proxy endpoint must match the Common Name in the server's certificate

Since it is not possible to configure an SSL connection, Ice for ActionScript does not implement an IceSSL plug-in or support the IceSSL configuration properties that are available in other language mappings. There is no need to explicitly install SSL support; it is always available in run-time environments that support it. To use SSL, you simply include an SSL endpoint in the proxy:

MyObject:ssl -h myserver.domain.com -p 9999

In this example, the ActionScript run time will reject the connection if the server certificate's Common Name does not match myserver.domain.com. For this reason, Ice does not perform a DNS query for host names in SSL endpoints.

If you intend to use SSL to connect to a Glacier2 router, note that it is not possible to create a router session using the createSessionFromSecureConnection operation because the client cannot supply its own certificate; you must use password authentication instead.

On the server side, you must configure your server's IceSSL plug-in to set the IceSSL.VerifyPeer property to a value of 0 or 1. The default value of this property (2) causes the server to reject a connection if the client does not supply a certificate.

Finally, please be aware of this SSL issue.

DNS limitations

For a proxy endpoint that uses TCP, the Ice run time for AIR performs a DNS query to resolve the endpoint's host name into one or more IP addresses. Specifying a multi-homed host name in an endpoint provides the client with a simple form of fault tolerance because Ice has multiple addresses to use during connection establishment.

This form of fault tolerance is not available when using Ice with Flash because the DNS API is not supported. This feature is also not supported for SSL endpoints.

Flash socket policy files

While running within the Flash sandbox, all outgoing socket connections are validated using the rules in a policy file. This file, which is typically supplied by the remote host, specifies the ports to which the program is allowed to connect.

An Adobe article provides more information on socket policy files.

Asynchronous APIs in Ice for ActionScript

Given ActionScript's lack of support for threads, Ice for ActionScript uses asynchronous semantics in every situation that has the potential to block, including both local and non-local invocations. Synchronous proxy invocations are not supported.

Here is an example of a simple proxy invocation:

var proxy:HelloPrx = HelloPrxHelper.uncheckedCast(...);
var result:Ice.AsyncResult = proxy.sayHello();
result.whenCompleted(handleResponse, handleException);

function handleResponse(r:Ice.AsyncResult):void
{
    ...
}

function handleException(r:Ice.AsyncResult, ex:Ice.Exception):void
{
    ...
}

The API design is similar to Ice for .NET in that the return value of a proxy invocation is an instance of Ice.AsyncResult, through which the program configures callbacks to handle the eventual success or failure of the invocation.

Certain operations of local Ice run-time objects can also block, either because their implementations make remote invocations, or because their purpose is to block until some condition is satisfied:

• Communicator::destroy
• Communicator::waitForShutdown
• Communicator::createObjectAdapter
• Communicator::createObjectAdapterWithEndpoints
• Communicator::createObjectAdapterWithRouter
• Communicator::getAdmin
• Connection::close
• ObjectAdapter::activate
• ObjectAdapter::deactivate
• ObjectAdapter::waitForHold
• ObjectAdapter::waitForDeactivate
• ObjectAdapter::destroy
• ObjectAdapter::refreshPublishedEndpoints
• ObjectPrx::ice_getConnection

These operations use the same asynchronous API as for proxy invocations. Here is an example that shows how to call createObjectAdapter:

var communicator:Ice.Communicator = ...;
var result:Ice.AsyncResult = communicator.createObjectAdapter("MyAdapter");
result.whenCompleted(adapterCreated, handleException);

function adapterCreated(r:Ice.AsyncResult, adapter:Ice.ObjectAdapter):void
{
    ...
}

function handleException(r:Ice.AsyncResult, ex:Ice.Exception):void
{
    ...
}

Finally, Ice for ActionScript provides two methods for initializing a communicator:

package Ice {
public class Util
{
    public static function initialize(...):Communicator;

    public static function initializeWithAdmin(...):AsyncResult;
}
}

The majority of Ice for ActionScript programs can use the traditional initialize method. However, an Ice server that enables the administrative facility must use the asynchronous method initializeWithAdmin.

Known Problems in Ice for ActionScript 1.0b

Hang during SSL connection establishment

During our testing, we have experienced occasional hangs when an outgoing SSL connection is being established. This appears to be caused by a bug in the AIR 2 run time, therefore we do not recommend using SSL in a production environment without extensive testing.

Using the Windows Binary Distribution

Distribution contents

The Ice for ActionScript binary installer includes the following components:

• Slice-to-ActionScript compiler (slice2as.exe)
• Ice for ActionScript run-time library (Ice.swc)
• Several sample programs
• Standard Slice files

Note that the installer does not include the Flash Builder plug-in, which you must install separately. Also note that the Slice files in this distribution are identical to those of Ice 3.4.2, except for some metadata changes.

Sample programs

During installation, the sample programs are installed by default in a sub-folder of the Documents or My Documents folder of the user who performed this installation. You'll find a shortcut to this directory in your Start menu. You can also download a ZIP archive of these sample programs, and extract this archive in a folder of your choice.

The sample programs are in source form only. Please refer to the README.txt file in the top-level folder for instructions on how to build and use them.