TechNote

Adobe Flash Remoting MX for Java Hot Fix

This hot fix represents a complete replacement of the binary files for Adobe Flash Remoting MX for Java version 1.0.

This hot fix provides an update to Adobe Flash Remoting MX for Java. It addresses a memory leak and security enhancements that were identified during the development of Adobe Flex's RemoteObject feature (see the technical description section for more information).

To support these new enhancements this version of the Adobe Flash Remoting gateway introduces a new method of configuration as well as a dependency on a new library, Apache Commons BeanUtils v1.6.

Prerequisites:

A valid serial number is still required to use this product.

Related Bugs:

81838 - Flash Remoting memory leak discovered during MTBF testing

Technical description:

A memory leak was discovered during load testing of the gateway during development of Macromedia Flex's RemoteObject feature. The leak was caused by the ServiceAdapter failing to create consistent keys from service resolutions - a step that matches a service name to a service adapter.

The development of Flex's RemoteObject feature also required enhancements to the security features of the Flash Remoting gateway. Developers can now restrict access to a limited subset of services using a whitelist, disable entire service types and configure the order in which service types are queried when locating a service, and stop stack traces from being sent to the client when an error occurs.

The following highlights some of the features of the new Adobe Flash Remoting MX gateway configuration file.

Adding a serial number for Adobe Flash Remoting MX for Java

Prior to this hot fix, Adobe Flash Remoting MX's serial number was configured in the frconfig.txt properties file either by the installer or manually added by the developer. The new configuration file obviates the legacy frconfig.txt file; the serial number is now added as the body of the <sn> tag in gateway-config.xml.

 <gateway-config>    ...<sn>FRD100-XXXXX-XXXXX-XXXXX</sn></gateway-config>

Changing the logging level of the gateway

The logging level was previously configured via a servlet init parameter 'LOG_LEVEL' in web.xml. This method is no longer supported and must now be configured in the new gateway-config.xml file using the level attribute of the <logger> tag.

 <gateway-config>    ...<logger level="Error">flashgateway.log.DefaultLogger</logger></gateway-config>

The level attribute can be set to 'None', 'Info', 'Warning', 'Error' or 'Debug'.

Configuring access to services using a whitelist

A whitelist specifies which remote sources can be accessed through the gateway. The source name depends on the type of service being accessed. For the Java Adapter, the source is a fully qualified classname; for the EJB Adapter, it is the JNDI name of an EJB. The * character can be used as a wildcard at the end of service names.

 <gateway-config>    ...<security>    ...<whitelist><source>flashgateway.samples.*</source></whitelist></security>    ...</gateway-config>

In the above example, the * character implies that all Java class-based services in the flashgateway.samples package can be accessed through the gateway. Note that a source that is simply a single * character implies ALL services - this is not suggested in production mode for security reasons.

Preserving the case of complex object properties

Due to the fact that ActionScript 1.0 object properties were case-insensitive, the gateway forced all ActionScript property names to lowercase to ensure only one value for a property could be specified. Now that ActionScript 2.0 (which is case-sensitive) is widely used it is expected that developers will want to disable lowercase keys for complex objects and preserve the original case of the property names.

To avoid lowercased property names, simply set the lowercase-keys property to false in the new gateway-config.xml file.

 <gateway-config>    ...<lowercase-keys>false</lowercase-keys></gateway-config>

Using enhanced complex object serialization

Now that ActionScript 2.0 has introduced formal class structures it is suggested that Adobe Flash Remoting developers change the default configuration to use the new serialization features that were driven by Macromedia Flex's RemoteObject feature.

Simply set the serialization tag to 'Flex' in the new gateway-config.xml file.

 <gateway-config>    ...<serialization>Flex</serialization></gateway-config>

Setting serialization to 'Flex' informs the gateway to use ASTranslator-like, Java Bean serialization logic when returning complex objects from the server and optimizes large object graphs by serializing commonly occuring objects by reference, including support for circular references.

Disable a type of service

The gateway configuration file lists the service adapters that are to be used when locating a service. It is likely that in most deployments the developer will know which type of services they will require and may wish to disable the adapters that will never be used.

An example of this may be on an application server that doesn't support EJBs. To disable EJB support in the gateway, simply comment out the EJBAdapter entry from the list of service-adapters in gateway-config.xml:

 <gateway-config><service-adapters><adapter>flashgateway.adapter.resultset.PageableResultSetAdapter</adapter><adapter type="stateful-class">flashgateway.adapter.java.JavaBeanAdapter</adapter><adapter type="stateless-class">flashgateway.adapter.java.JavaAdapter</adapter><!-- <adapter type="ejb">flashgateway.adapter.java.EJBAdapter</adapter> --><adapter type="servlet">flashgateway.adapter.java.ServletAdapter</adapter></service-adapters>    ...</gateway-config>

Installation Instructions:

Stop the application server(s).
Download the hot fix (ZIP, 323K).
Unzip the hot fix ZIP file to a temporary directory.
Copy /WEB-INF/lib/*.* to the web application's /WEB-INF/lib directory.
Copy /WEB-INF/gateway-config.xml to the web application's/WEB-INF directory.

Open /WEB-INF/web.xml and note the new servlet configuration. Use this information to update your web application's /WEB-INF/web.xml deployment descriptor for the Flash Remoting MX gateway servlet.

A sample of the new servlet configuration is included below:

 <servlet><servlet-name>FlashGatewayServlet</servlet-name><display-name>Flash Remoting Gateway Servlet</display-name><description>Servlet-based plugin to Flash Remoting</description><servlet-class>flashgateway.controller.GatewayServlet</servlet-class><init-param><param-name>gateway.configuration.file</param-name><param-value>/WEB-INF/gateway-config.xml</param-value></init-param><init-param><param-name>whitelist.configuration.file</param-name><param-value>/WEB-INF/gateway-config.xml</param-value></init-param><init-param><param-name>whitelist.parent.node</param-name><param-value>gateway-config</param-value></init-param><load-on-startup>1</load-on-startup></servlet>

Restart your application server.

Modified files:

The hot fix contains the following files:

/README.txt (this file)
/WEB-INF/gateway-config.xml
/WEB-INF/web.xml
/WEB-INF/lib/commons-beanutils.jar
/WEB-INF/lib/flashgateway.jar

The following briefly describes the purpose of each file in this distribution:

/WEB-INF/web.xml

A web application deployment descriptor file that demonstrates the new servlet init parameters for the Flash Remoting MX gateway. It is intended that the user simply modifies their existing deployment decriptor with these new configuration settings. Note that the legacy servlet init parameters such as LOG_LEVEL, DISABLE_JAVA_ADAPTERS and DISABLE_CFWS_ADAPTERS are no longer supported and should be removed from existing gateway servlet configurations.

/WEB-INF/gateway-config.xml

A new configuration file that replaces the legacy frconfig.txt file. This file, among other things, allows ou to lock down access to a small number of services and disable certain service adapters.

/WEB-INF/lib/flashgateway.jar

This is an updated version of the core Flash Remoting library. The version and build number of Flash Remoting is contained inside the JAR file manifest, i.e. the /META-INF/MANIFEST.MF file.

/WEB-INF/lib/commons-beanutils.jar

A new library is required to support the ASTranslator serialization rules for typed complex objects that was inroduced for the Remote Object feature in Adobe Flex 1.0. Flash Remoting customers can also benefit from these enhancements.