Personal tools

Views

BlazeDS:Release Notes

From Adobe Labs

Table of contents
1 Features and Benefits of BlazeDS
2 Installing BlazeDS

2.1 BlazeDS with integrated Tomcat

2.1.1 Running the TestDrive with the integrated Tomcat install

2.2 BlazeDS J2EE web applications
2.3 Additional server-specific configuration

2.3.1 Tomcat
2.3.2 WebSphere
2.3.3 JBoss
2.3.4 Running from a compressed WAR

2.4 Integrating BlazeDS with a ColdFusion 8 installation

3 Documentation

3.1 Usage Information
3.2 Reference

4 Known Issues

Features and Benefits of BlazeDS

Feature

Description

Real-world use or benefit

Java remoting

Remoting provides a call and response model for accessing external data from Flex or Ajax applications. Developers can create applications that make asynchronous requests to remote services, including HTTP services, SOAP-based web services, and direct invocation of native Java objects. BlazeDS provides transparent data transfer between ActionScript and Java data types, including data structures that use Java 5 enumerations

High-performance binary data transfer between client and server is dramatically faster than textual protocols, such as SOAP or XML.

Web proxy

Enables communication between the Flex or Ajax clients and domains they cannot access directly, due to security restrictions, allowing developers to integrate multiple services with a single RIA.

Access to data distributed across domains.
Reduce the opportunity for malicious discovery of security credentials used to access applications exposed as web or HTTP services.

Runtime configuration

Provides server-side APIs that let developers create and delete data services, adapters, and destinations, which can be modified even after the server is started.

This dynamic component creation at runtime makes it easy to integrate existing code in a Flex or Ajax application. With this feature, the client code is pointed at the server and it gets any configuration it needs from the server when it connects.

Publish and subscribe messaging over HTTP

Publish and subscribe to message topics in real time using HTTP streaming or long polling (COMET) with the same reliability and overall quality of service as traditional thick client applications, enabling the creation of innovative and collaborative real-time experiences.

The messaging and real time infrastructure, using native web protocols, enables collaboration and data push applications to be built in a reliable manner while using native web protocols, scaling to hundreds of clients per CPU.Real-time examples include performance monitoring, real-time news feeds, and incident tracking. Collaboration examples include chat, assisted selling, live help, and guided self-service.

Open adapter architecture

BlazeDS provides an open adapter architecture to easily integrate with JMS, EJBs, ColdFusion components and other data sources. The adapter architecture allows you to integrate with any kind of messaging system.

The BlazeDS adapter architecture is open and customizable, allowing connectivity to any back-end data system or application. Once the appropriate destinations have been configured, the RIA developer can access them through a set of client APIs, either in MXML or ActionScript.

Java Message Service (JMS) adapter

Allows Flex applications to publish and subscribe to JMS topics and queues. Java applications can publish messages to Flex and Ajax, and Java code can respond to messages that Flex and Ajax applications send.

The JMS adapter allows RIAs to easily integrate with backend applications and business processes. Examples: Provide an RIA management interface to watch the progress of sales invoices across multiple backend systems.  Subscribe to real-time market data feeds that are available via JMS queues.

Server-side component framework integration

Developers can directly expose components in their frameworks, such as Spring or EJB, to Flex clients without writing any code.

Example: The Adobe Component Exchange offers free downloads for a SpringFactory and an EJB Factory.   Spring is a widely used component framework and EJB is a component framework defined as part of the Java EE standard.  Using these factories, developers can expose components directly to Flex or Ajax clients without writing any code.

Action Message Format (AMF) transport protocol

AMF3 is a very compact binary format for data serialization/deserialization and remote method invocation. A key feature of this format is that it preserves the entire graph of your data without duplicating identical objects.  Object encoding controls how objects are represented in Action Message Format (AMF). Flash Player uses AMF to enable efficient communication between a Flash/Flex application and a remote server. AMF encodes remote procedure calls into a compact binary representation that can be transferred over HTTP/HTTPS. ActionScript objects and data values are serialized into this binary format, which is generally more compact than other representations, such as XML.

Data delivery performance when using AMF is up to 10 times faster than applications delivering data payloads using plain XML over HTTP or web services.  As data size increases the performance benefits of using BlazeDS increase exponentially. 
AMF improves performance by 1) dramatically compressing the size of data transferred and 2) parsing binary data into objects in memory far more efficiently than parsing XML data.

Monitoring and management console

Graphical administrative console for BlazeDS provides the ability to view and control performance and resource information as well as expose server configuration and server properties.  General server metrics allow the user to view and control the current overall state of the server. Such statistics can be graphed as a time series by polling the server for the requested metrics at regular intervals.

Visibility and control over the BlazeDS server configuration and runtime performance. Fine-grained resource control allows the user to view all or individual exposed resources which reflect resource usage at a more granular level, allowing an administrator to find those which are the most resource intensive and to take proper action.

Clustered messaging

When you deploy applications where the server pushes messages to the client, you need to ensure that messages are properly routed across the cluster to connect producers and consumers no matter which server they are connected to.  BlazeDS handles this by providing a high performance and efficient clustered messaging implementation [leveraging the open source jgroups messaging libraries].

Software clustering handles failover when using stateful services to ensure that applications continue running in the event of server failure.  The more common form of clustering using load balancers, usually in the form of hardware, is supported without any feature implementation.

Ajax Client Library

With this library, distributed with the open source Flex SDK, developers can integrate Ajax client applications with the same back-end data services used by Flex application clients, including remoting and messaging.

The Ajax client library allow the RIA developer to create advanced user experiences that blend Flex and Ajax, with a common programming model for remoting and messaging.

Internet Protocol Version 6 (IPV6)

BlazeDS supports IPV6-style URLs in configuration files and code.

You can use IPV6 with an application server that supports it, such as Apache Tomcat 5.5.x, BEA WebLogic, JBoss, or IBM WebSphere.

Installing BlazeDS

BlazeDS runs in a J2EE web application and is available in ZIP files for the following configurations:

BlazeDS runs on the following platforms:

These installation instructions refer to root directory where you unzip the BlazeDS ZIP file as install_root.

BlazeDS includes the following Web Application Archive (WAR) files:

Each WAR file is a separate, stand-alone web application. If you are using the J2EE web application option, you must have an existing J2EE application server or servlet container available and understand web application deployment. If you do not have an existing J2EE server or are not familiar with WAR file deployment, use the integrated Tomcat configuration to get started.

BlazeDS with integrated Tomcat

The BlazeDS with integrated Tomcat ZIP file contains the following files and directories under the installation root:

readme.htm Contains an overview of important information.
blazeds.war BlazeDS web application, used as a starting point for new applications.
blazeds-samples.war BlazeDS sample applications.
blazeds-console.war Simple monitoring application for BlazeDS deployments.
license.txt license information.
/tomcat Contains an installation of Apache Tomcat that includes blazeds, blazeds-samples, and blazeds-console web applications expanded and deployed in the default server.
/resources Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex Ajax Bridge, WSRP, and manually creating HTML wrappers. Flash Player installers are in the Flex SDK ZIP file.

To install BlazeDS in the integrated Tomcat configuration:

  1. Read the BlazeDS release notes for known issues and any late-breaking information.
  2. Unzip the ZIP file to a local directory on your file system.
  3. Make sure that the machine you are installing on has a Java Development Kit (JDK) installed and a JAVA_HOME environment variable.
  4. To start BlazeDS, open a command window, navigate to install_root/tomcat/bin, and enter the catalina start command. On UNIX and Linux, enter ./catalina start. Optionally, on Windows you can navigate to the install_root/tomcat/bin in Windows Explorer and double-click the catalina.bat icon.

Running the TestDrive with the integrated Tomcat install

In addition to the BlazeDS war file, the BlazeDS download includes a version of Tomcat (6.0.14) with a series of web applications fully configured with BlazeDS (including blazeds-sample). To run the test drive after downloading and expanding the integrated Tomcat install:

  1. Start Tomcat (startup.bat or startup.sh in /blazeds/tomcat/bin)
  2. Open a browser and access the samples home page:
    http://localhost:8400/blazeds-samples/
  3. Take the test drive!

BlazeDS J2EE web applications

The BlazeDS J2EE web application option installs the following files and directories under the installation root:

readme.htm Contains an overview of important information.
blazeds.war BlazeDS web application, used as a starting point for new applications.
blazeds-samples.war BlazeDS sample applications.
blazeds-console.war Simple monitoring application for BlazeDS deployments.
license.txt license information.
/resources Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex-Ajax Bridge, WSRP, and manually creating HTML wrappers. Flash Player installers are in the Flex SDK ZIP file.

To install BlazeDS as a J2EE web application:

  1. Read the BlazeDS Release Notes for known issues and any late-breaking information.
  2. Unzip the BlazeDS ZIP file
  3. Deploy the blazeds, blazeds-samples, and blazeds-console web applications by using your application-server-specific deployment method. For example, for Tomcat, copy the WAR files to the webapps directory and restart the server.
  4. Perform additional application-server specific configuration, as described in Additional server-specific configuration.

Additional server-specific configuration

You may need to perform additional configuration steps for the following application servers:

Tomcat

To use BlazeDS with Tomcat, follow these steps after deploying the BlazeDS WAR files. These steps are not necessary for the integrated Tomcat installation.

  1. Increase the maximum memory to at least 512MB. This is achieved by specifying the maximum heap size for the JVM in the JAVA_OPTS variable: -Xmx512m
  2. (Optional) To enable custom authentication, locate the Tomcat security resource libraries under install_root/resources/security/tomcat.
    1. Put flex-tomcat-common.jar in common/lib
    2. Place flex-tomcat-server.jar in server/lib (NOT shared/lib)
    3. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors. For example, for the BlazeDS samples WAR:
      <Context path="/blazeds-samples" docBase="${catalina.home}/webapps/blazeds-samples" debug="0">
        <Valve className="flex.messaging.security.TomcatValve"/>
      </Context>
      You will now be authenticated against the current Tomcat realm. Usually, the default for this authentication stores user information in conf/tomcat-users.xml. See the Tomcat documentation for more information on realms. See the documentation for more information on BlazeDS custom authentication.
    4. You may also need to update the active <login-command> in /WEB-INF/flex/services-config.xml in each deployment of a BlazeDS WAR file. For Tomcat, ensure that the TomcatLoginCommand is active in the <security> section:
      <security>
        <login-command class="flex.messaging.security.TomcatLoginCommand" server="Tomcat" />
      ...
  3. (Optional) To use the JMSAdapter with the Message Service, you must install and configure a JMS provider (such as activeMQ or openJMS) for use with Tomcat.
  4. Restart Tomcat.

WebSphere

(Optional) To enable custom authentication, open the WebSphere Administrator and configure a custom user registry using the files under install_root/resources/security/websphere/ as usersFile and groupsFile custom properties.

JBoss

(Optional) To enable custom authentication, you must perform the following configuration steps:

  1. Put install_root/resources/security/tomcat/flex-tomcat-common.jar and install_root/resources/security/tomcat/flex-tomcat-server.jar in the jboss_root/server/default/lib folder.
  2. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors.
  3. Restart JBoss.

This configuration provides authentication against the current JBoss realm. Usually, the default for this authentication stores user information in jboss_root/server/default/conf/users.properties and roles information in jboss_root/server/default/conf/roles.properties. For more information on realms, see the JBoss documentation. For more information on BlazeDS custom authentication, see the BlazeDS documentation and information in the install_root/resources/security directory.

Running from a compressed WAR

To run BlazeDS from a compressed WAR file, perform the following steps:

  1. Expand the flex.war file using winzip or the JAR utility.
  2. Create your application, including SWF files, ActionScript files, configuration settings and HTML wrappers.

    Note: For more information on compiling SWF files and creating HTML wrappers, see the BlazeDS documentation.

  3. Create a compressed WAR file from the expanded web application structure.
  4. Deploy the compressed WAR file.

    5. Note that many samples applications in blazeds-samples.war use HSQLDB which will not function within a compressed web application. It is therefore advised to deploy blazeds-samples as an uncompressed war.

    Note that when running BlazeDS from a compressed WAR file some features, such as clustering are not available.

Integrating BlazeDS with a ColdFusion 8 installation

To integrate BlazeDS with ColdFusion 8 with integrated LiveCycle Data Services ES installation, perform these steps:

  1. Shut down ColdFusion.
  2. Move aside the ColdFusion8/wwwroot/WEB-INF/flex directory.
  3. Edit ColdFusion8/WEB-INF/web.xml:
    • Comment out/remove the definitions of FlexMxmlServlet and FlexInternalServlet servlets.
    • Comment out/remove the servlet mapping for FlexMxmlServlet and FlexInternalServlet.
    • Comment out/remove the taglig definition for the FlexTagLib tag library.
  4. Complete the following instructions for ColdFusion without Integrated LiveCycle Data Services ES.

To integrate BlazeDS with ColdFusion 8 without integrated LiveCycle Data Services ES installation, perform these steps:

  1. Shut down ColdFusion.
  2. Unzip blazeds.war in to a temporary directory (In this example c:\temp\BlazeDS).
  3. Move aside the following jar files from ColdFusion8/lib:
    • flex-messaging.jar
    • flex-messaging-common.jar
    • flex-messaging-opt.jar
    • flex-messaging-req.jar
  4. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/lib:
    • flex-messaging-common.jar
    • flex-messaging-core.jar
    • flex-messaging-opt.jar
    • flex-messaging-proxy.jar
    • flex-messaging-remoting.jar
  5. Create a new directory (create the WEB-INF/flex directory if needed):
    ColdFusion8/wwwroot/WEB-INF/flex/jars
  6. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/wwwroot/WEB-INF/flex/jars:
    • concurrent.jar
    • cfgatewayadapter
  7. Set up the configuration files for BlazeDS. You can copy the set of configuration files from the BlazeDS ZIP file (not the WAR file). Copy the following files in resources/ColdFusion to ColdFusion8/wwwroot/WEB-INF/flex:
    • services-config.xml
    • messaging-config.xml
    • proxy-config.xml
    • remoting-config.xml

(Optional)
You can continue to use the configuration files from your integrated LiveCycle Data Services ES installation by doing the following:

  1. Copy services-config.xml, messaging-config.xml, proxy-config.xml, and remoting-config.xml from the WEB-INF/flex directory you moved aside earlier back to ColdFusion8/wwwroot/WEB-INF/flex.
  2. Remove from the following line from the services-config.xml file: 
    <service-include file-path="data-management-config.xml" />
  3. Remove the <channel-definition> for the ColdFusion-specific RTMP channel (if not commented out) and remove the java-http and java-secure-http channel definitions.
  4. Uncomment the java-amf, java-secure-amf and java-polling-amf channels. Do not include the java-rtmp channel definition.
  5. Edit the proxy-config.xml file and change the lines: 
    <channel ref="java-http"/>
<!-- <channel ref="java-amf"/> -->

    to the following text: 

    <channel ref="java-amf"/>

Documentation

Usage Information

Usage documentation is available in HTML format on LiveDocs and as a PDF file:

Reference

The ActionScript and Java class reference documentation is available here in ZIP files:

Known Issues

Retrieved from "http://labs.adobe.com/wiki/index.php/BlazeDS:Release_Notes"