2.3. Surveying the Configuration Options

Before you start using BlazeDS gainfully, you need to learn how to configure BlazeDS to work with your application.

Simply put, at the heart of BlazeDS is a Servlet that bootstraps the infrastructure that intercepts all calls between a Flex client and the BlazeDS instance. This Servlet, called MessageBrokerServlet, uses artifacts like channels, endpoints, and adapters to enable proxy, remoting, and messaging services. A default configuration file, called services-config.xml, which lies in the WEB-INF/flex folder of the BlazeDS installation, defines these artifacts and their relationships in the context of the MessageBrokerServlet. We will peek into this configuration file in this section and continue to revisit it in the later chapters in the context of BlazeDS's various services. However, nothing in the configuration will make much sense unless you first understand the fundamentals of channels, endpoints, and adapters.

Channels and endpoints connect a Flex client to a BlazeDS server. They are the primary components that enable communication between these two entities. Endpoints reside at the BlazeDS end. Flex clients use channels to connect to these endpoints.

The BlazeDS endpoints are Servlet-based endpoints. Each endpoint defines a type and format of communication. For example, endpoints exist for simple AMF data exchange, polling AMF, and AMF data streaming.

Analogously, the Flex client defines a set of channels that vary depending on the type and format of communication. For example, the HTTPChannel facilitates communication over non-binary AMF format, AMFX (AMF in XML), and the AMFChannel enables standard binary AMF-based communication.

Matching endpoints and channels are paired, and that's when a Flex client and BlazeDS server talk to each other. The binding of channels and endpoints to their implementation classes and their pairing is done in the services-config.xml configuration file.

In addition to the endpoints, BlazeDS includes adapters that provide the critical compatibility between the core BlazeDS Servlet that talks to Flex and a server-side resource such as a JMS resource, a persistent data store, or an Object-Relational mapping layer. Adapters are also configured in services-config.xml.

You must be curious by now to see what services-config.xml looks like, and so that is what we look into next.

2.3.1. First Look at services-config.xml

The configuration file services-config.xml, in BlazeDS, is logically split into four configuration files. The top level and the first of these four is services-config.xml itself. The other three are as follows:

• remoting-config.xml

• proxy-config.xml

• messaging-config.xml

These three files are included in services-config.xml by reference as follows:

<services>
    <service-include file-path="remoting-config.xml" />
    <service-include file-path="proxy-config.xml" />
    <service-include file-path="messaging-config.xml" />
</services>

The names of the configuration files suggest what they configure. remoting-config.xml is where all remoting related destination, endpoint, and adapter configuration resides. proxy-config.xml holds the proxy service settings, and messaging-config.xml defines the messaging resources, adapters, and their properties.

You will learn more about the contents of each of these files soon. However, first let's explore the top-level configurations that reside in the main file, services-config.xml.

Standard channels and corresponding endpoints are defined as shown in Listing 2-1.

Example 2.1. : Channel and Corresponding Endpoint Definition in services-config.xml

<channels>
    <channel-definition id="my-amf" class="mx.messaging.channels.AMFChannel">
        <endpoint url="http://{server.name}:{server.port}/{context.root}/
    messagebroker/amf"

class="flex.messaging.endpoints.AMFEndpoint"/>
    </channel-definition>

    <channel-definition id="my-secure-amf"
        class="mx.messaging.channels.SecureAMFChannel">

        <endpoint url="https://{server.name}:{server.port}/{context.root}/
    messagebroker/amfsecure"
    class="flex.messaging.endpoints.SecureAMFEndpoint"/>
        <properties>
            <add-no-cache-headers>false</add-no-cache-headers>
        </properties>
    </channel-definition>

    <channel-definition id="my-polling-amf"
       class="mx.messaging.channels.AMFChannel">

       <endpoint url="http://{server.name}:{server.port}/{context.root}/
    messagebroker/amfpolling"
    class="flex.messaging.endpoints.AMFEndpoint"/>
        <properties>
            <polling-enabled>true</polling-enabled>
            <polling-interval-seconds>4</polling-interval-seconds>
        </properties>
    </channel-definition>


   <channel-definition id="my-http" class="mx.messaging.channels.HTTPChannel">

        <endpoint url="http://{server.name}:{server.port}/{context.root}/
     messagebroker/http"
     class="flex.messaging.endpoints.HTTPEndpoint"/>
    </channel-definition>

    <channel-definition id="my-secure-http"
     class="mx.messaging.channels.SecureHTTPChannel">

        <endpoint url="https://{server.name}:{server.port}/{context.root}/
    messagebroker/httpsecure"
    class="flex.messaging.endpoints.SecureHTTPEndpoint"/>
        <properties>
            <add-no-cache-headers>false</add-no-cache-headers>
        </properties>
    </channel-definition>
</channels>

The code in listing 2-1 creates five types of channels:

• AMF channel

• Secure AMF channel

• Polling AMF channel

• HTTP channel

• Secure HTTP channel

If you look closer, the three AMF channels are quite similar. AMF and Secure AMF use different implementation classes and use http and https endpoints, respectively, for communication, but share a common binary format for information exchange. Polling AMF adds polling capabilities on the standard AMF channel. The polling-enabled property is set to true and polling-interval-seconds sets a polling frequency of 4 seconds for repetitive invocations.

The HTTP channel and secure HTTP channel set up channels for non-binary data transfer using XML over AMF.

Apart from the channels, you define other cross-cutting concerns such as security, logging, and configuration file deployment characteristics in the top-level configuration file. The logging settings could be as follows:

<logging>
        <target class="flex.messaging.log.ConsoleTarget" level="Debug">
            <properties>
                <prefix>[BlazeDS] </prefix>
                <includeDate>false</includeDate>
                <includeTime>false</includeTime>
                <includeLevel>false</includeLevel>
                <includeCategory>false</includeCategory>
            </properties>
            <filters>
                <pattern>Endpoint.*</pattern>
                <pattern>Service.*</pattern>
                <pattern>Configuration</pattern>
            </filters>
        </target>
    </logging>

You will learn a lot more about logging in Chapter 4. With a cursory glance, you can easily notice that console is set as the target of the log messages, and the logging level is set to a debug level.

Next, we rapidly browse through important sections of the other three log files.

2.3.2. Remoting, Proxy and Messaging Configuration

One of the key configurations for remoting relates to the destination. A destination is a logical handle to a remote service, on which a remote procedure can be invoked. Adapters and channels are also associated with a destination. You will see a simple Java remote service in action in the next section. Both code and configuration for the simple example are explained there. In that example a Java adapter is in use. A Java adapter is included as follows:

<adapters>
    <adapter-definition id="java-object"
class="flex.messaging.services.remoting.adapters.JavaAdapter" default="true"/>
</adapters>

The remoting service is central to BlazeDS and is explained at length at many points in this book, so there isn't more discussion on it here.

The messaging service, like the remoting service, uses a destination and an associated set of adapters and channels. The destination configurations for messaging and remoting are similar. The adapter for messaging could include a JMS adapter, which can accept a number of settings, which are specified in the messaging-config.xml file. You have not been given any background on messaging yet, so talking about its configuration is premature. Anything that is related to messaging will only make sense when discussed in context and that will not happen until Chapter 6. If you can't control your excitement, jump over to that chapter and find out more.

The last of the configuration trio is the proxy configuration. Proxy service allows HTTP and SOAP requests to be tunneled through the server to work around the constraints imposed by the lack of security specifications at a remote destination. BlazeDS defines adapters to work with both HTTP and SOAP protocols. Including the adapters and setting them up while bootstrapping means specifying them as follows:

<adapters>
    <adapter-definition id="http-proxy"
class="flex.messaging.services.http.HTTPProxyAdapter" default="true"/>
              <adapter-definition id="soap-proxy"
class="flex.messaging.services.http.SOAPProxyAdapter"/>
</adapters>

While a lot more can be covered on configuration, I think this may be enough to get a sense of what is involved. Finally time to dig into an elementary but working example that uses BlazeDS to converse between Flex and Java.