9.2. The API

BlazeDS exposes a public Java API. You can leverage that API to customize the behavior of BlazeDS resources.

Before you start using the API it's a must that you explore it thoroughly and understand the role of some of its main classes. A good starting point of exploration is a sketch of its key classes and their interrelationships. Figure 9-3 provides such a sketch.

The flex.messaging.services.ServiceAdapter abstract class sits at the root of the hierarchy depicted in Figure 9-3. All built-in adapter classes inherit from the ServiceAdapter abstract class. Abstract classes not only define a contract like interfaces do but also define behavior through partial method implementations. The ServiceAdapter class states the base behavioral characteristics of a BlazeDS adapter.

The ServiceAdapter class extends the ManageableComponent class. The ManageableComponent abstract class implements the Manageable and the FlexComponent interfaces. The Manageable interface allows a server-side BlazeDS component to be managed and controlled by a peer MBean. The FlexComponent interface defines the lifecycle methods that allow you to instantiate, initialize, start, and stop a component.

Figure 9.3. Figure 9-3

Apart from the lifecycle's "start" and "stop" methods, which start and stop an adapter, the ServiceAdapter class defines the following methods:

• A getter and setter pair to get and set a destination.

• A getter and setter pair to get and set the adapter state.

• The manage method to perform an internal action based on a command passed to it by the adapter's service.

• The invoke method to process the data message for the adapter. This is the most important method of all. All core adapter functions that translate data format or apply logic on the message are referenced from this method

• The handlesSubscriptions method; this method returns a Boolean value, which when "true" states that the adapter manages subscriptions.

Three main built-in adapters, flex.messaging.services.http.HTTPProxyAdapter, flex.messaging.services.remoting.adapters.JavaAdapter, and flex.messaging.services.messaging.adapters.MessagingAdapter, directly extend from the ServiceAdapter. MessagingAdapter is an abstract class and is not used directly. However, it defines the essential behavioral characteristics of a messaging adapter. The ActionScriptAdapter and the JMSAdapter extend from the MessagingAdapter. The SOAPProxyAdapter extends from the HTTPProxyAdapter. Therefore, all built-in adapters in BlazeDS extend directly or indirectly from ServiceAdapter.

The hierarchical structure of adapter classes creates a clear separation of features. It provides a structure where the core features are part of the base abstract classes and the communication style and server-side entity–specific features are part of the extensions to the base classes. Therefore, depending on the set of features you want, you can extend ServiceAdapter or one of its subclasses to create a custom adapter.

The HTTPProxyAdapter defines a few additional methods besides the core methods available in the ServiceAdapter class, to manage connections, set cookie limits, manage external proxies, allow content chunking, and permit self-signed certificates in SSL-based communication.

From Chapter 3, you know that an HTTPProxyAdapter can be initialized with a set of properties that can be configured with an HTTPProxyService instance in proxy-config.xml as follows:

<connection-manager>
    <max-total-connections>150</max-total-connections>
    <default-max-connections-per-host>2</default-max-connections-per-host>
    <connection-timeout>0</connection-timeout>
    <socket-timeout></socket-timeout>
    <stale-checking-enabled></stale-checking-enabled>
    <send-buffer-size></send-buffer-size>
    <receive-buffer-size></receive-buffer-size>
    <tcp-no-delay>true</tcp-no-delay>
    <linger>-1</linger>
    <max-per-host>
        <host>hostname</host>
        <port>80</port>
        <protocol>http</protocol>
        <protocol-factory class="flex.messaging.services.http.ProtocolFactory">
            <properties>
            </properties>
        </protocol-factory>
        <max-connections>2</max-connections>
        <proxy>
            <host></host>
            <port>80</port>
        </proxy>
        <local-address></local-address>
        <virtual-host></virtual-host>
    </max-per-host>
</connection-manager>
<cookie-limit>200</cookie-limit>
<allow-lax-ssl>false</allow-lax-ssl>
<content-chunked>false</content-chunked>
<external-proxy>
    <server></server>
    <port>80</port>
    <nt-domain></nt-domain>

<username></username>
    <password></password>
</external-proxy>

These properties define the core behavior of the adapter and help it connect with external HTTP resources, which is what its primary role is. Refer to Chapter 3 to read more about these properties and other settings on the HTTPProxyService.

Information for a proxy request is stored in a ProxyContext. A ProxyFilter performs the tasks of pre- and post-processing on the ProxyContext when a message passes through an instance of the HTTPProxyAdapter. The SOAPProxyAdapter extends the HTTPProxyAdapter and acts as a placeholder for supporting future web services features.

The HTTPProxyAdapter or the SOAPProxyAdapter is a good extension point if you desire to include specific properties and behavior with HTTP requests or web services. Such services could include a specific authentication mechanism, encryption, and support for specific formats or protocols.

Besides HTTP request-response and web services–based communication, BlazeDS allows remote procedure call–based communication with Java server-side objects, using the JavaAdapter. You are already familiar with the JavaAdapter from Chapter 4.

JavaAdapter extends ServiceAdapter. It allows a Flex client to invoke the methods of a server-side Java class. By default, all methods of a target Java class can be invoked through the JavaAdapter. However, if required, the JavaAdapter allows you to include only a select set of a class's methods or exclude a few selected methods. Therefore, a JavaAdapter class has methods to include and exclude target Java class methods and manage the list of such included or excluded methods. The available methods for managing the inclusion and exclusion of target class methods are:

• addExcludeMethod(RemotingMethod value) —Add a method to the list of excluded methods

• addIncludeMethod(RemotingMethod value) —Add a method to the list of included methods

• getExcludeMethodIterator()—Get an Iterator over the currently registered exclude methods

• getIncludeMethodIterator()—Get an Iterator over the currently registered include methods

• removeExcludeMethod(RemotingMethod value)—Remove a method from the list of excluded methods

• removeIncludeMethod(RemotingMethod value)—Remove a method from the list of included methods

Flex and Java applications can interact with messages and remote procedure calls. Message-based interactions between Flex and Java leverage JMS on the server side. To talk with JMS, BlazeDS includes a JMSAdapter. JMSAdapter extends MessagingAdapter and plays well with the JavaAdapter to pass Java objects through as messages. In Chapter 6, you learned a whole lot about message-based integration between Flex and Java. Refer to that chapter for details on this topic.

The MessagingAdapter abstract class supports publish/subscribe messaging. It's the base class for all publish/subscribe messaging adapters in BlazeDS. It has two implementations in ActionScriptAdapter and JMSAdapter. ActionScriptAdapter facilitates publish/subscribe messaging between two Flex clients via a BlazeDS server. A MessageService instance controls the message delivery for an ActionScriptAdapter. An ActionScriptAdapter relies on a simple routing logic, where it sends a message using a MessageService's following two methods:

• pushMessageToClients—delivers message to all clients connected to a server

• sendPushMessageFromPeer—delivers messages to peer servers in the cluster, which in turn deliver the message to connected clients

Unlike the ActionScriptAdapter, the JMSAdapter is a lot more complicated in terms of the style and idioms it follows for message delivery. The JMSAdapter delivers messages using the JMS communication model. The JMSAdapter manages the queue and topic producers and consumers and sets JMS specific properties. Refer to Chapter 6 for details on how a JMSAdapter can be configured. You can extend a JMSAdapter to include additional features and properties if a particular JMS provider included provider specific extensions that you are required to use with your Flex application.

In this section, all the built-in adapters and their API have been surveyed so far. This should help you get started on creating a custom adapter.