The most common tasks that you perform when configuring the Messaging Service are defining message destinations and applying security to message destinations. Typically, you configure the Messaging Service in the messaging-config.xml file. The services-config.xml file includes the messaging-config.xml file by reference.

The following example shows a basic Message Service configuration in the messaging-config.xml file. It contains the following information:

• A service definition of the Message Service
• A reference to the MessageService class.
• A definition of the ActionScriptAdapter.
• A destination definition that references two channels. You define channels outside the destination definition.

<service id="message-service"
    class="flex.messaging.services.MessageService">
    <adapters>
        <adapter-definition 
            id="actionscript"
            class="flex.messaging.services.messaging.adapters.ActionScriptAdapter" 
            default="true"/>
        <adapter-definition id="jms"
            class="flex.messaging.services.messaging.adapters.JMSAdapter"/>
    </adapters>
    <destination id="chat-topic">
        <properties>
            <server>
                <message-time-to-live>0</message-time-to-live>
            </server>
        </properties>
        <channels>
            <channel ref="samples-rtmp"/>
            <channel ref="samples-amf-polling"/>
        </channels>
    </destination>
</service>

Configuring the adapter

To use a , such as the ActionScript, JMS, or ColdFusion Event Gateway Adapter, you reference the adapter in a destination definition. If you do not explicitly specify an adapter, the destination uses the default adapter as defined in the <adapters> tag. In addition to referencing an adapter, you also set its properties in a destination definition.

The following example shows two adapter definitions: the ActionScriptAdapter and the JMSAdapter. In this example, the ActionScriptAdapter is defined as the default adapter:

<service id="message-service"
    class="flex.messaging.services.MessageService">
    ...
    <adapters>
        <adapter-definition 
            id="actionscript"
            class="flex.messaging.services.messaging.
            adapters.ActionScriptAdapter" default="true"/>
        <adapter-definition 
            id="jms"
            class="flex.messaging.services.messaging.adapters.JMSAdapter"/>
    </adapters>
    ...
    <destination id="chat-topic">
        ...    
        <adapter ref="actionscript"/>
        ...
    </destination>
    ...
</service>

Since ActionScriptAdapter is defined as the default adapter, you can omit the <adapter> tag from the destination definition,

Defining the destination

You perform most of the configuration for the Messaging Service in the destination definition, including specifying the adapter and channels used by the destination, and any network and server properties.

Setting network properties in the destination

A destination contains a set of properties for defining client-server messaging behavior. The following example shows the network-related properties of a destination:

<destination id="chat-topic">
    <properties>
        <network>
            <throttle-inbound policy="ERROR" max-frequency="50"/>
            <throttle-outbound policy="ERROR" max-frequency="500"/>
        </network>
    </properties>
</destination>

Message Service destinations use the following network-related properties:

Setting server properties in the destination

A destination contains a set of properties for controlling server-related parameters. The following example shows server-related properties of a destination:

<destination id="chat-topic">
    <properties>
    ...
        <server>
            <message-time-to-live>0</message-time-to-live>
        </server>
    </properties>
</destination>

Message Service destinations use the following server-related properties:

Referencing message channels in the destination

The following example shows a destination referencing a channel. Because the samples-rtmp channel is listed first, it is used first and only if a connection cannot be established does the client attempt to connect over the rest of the channels in order of definition.

<destination id="chat-topic">
    ...        
    <channels>
        <channel ref="samples-rtmp"/>
        <channel ref="samples-amf-polling"/>
    </channels>
    ...
</destination>

For more information about message channels, see Channels and endpoints.

Applying security to the destination

One way to secure a destination is by using a security constraint, which defines the access privileges for the destination. You use a security constraint to authenticate and authorize users before allowing them to access a destination. You can specify whether to use basic or custom authentication, and indicate the roles required for authorization.

Two security properties that you can set for a messaging destination include the following:

• send-security-constraint

  Specifies the security constraint for a Producer component sending a message to the server.

• subscribe-security-constraint

  Specifies the security constraint for a Consumer component subscribing to a destination on the server.

You use these properties in a destination definition, as the following example shows:

<destination id="chat">
    ...
    <properties>
        <server>
            <send-security-constraint ref="sample-users"/>
            <subscribe-security-constraint ref="sample-users"/> 
        </server>
    </properties>
    ...
</destination>

In this example, the properties reference the sample-users security constraint defined in the services-config.xml file, which specifies to use custom authentication:

<security>
    <login-command class="flex.messaging.security.TomcatLoginCommand" server="Tomcat"> 
        <per-client-authentication>false</per-client-authentication>
    </login-command>
    <security-constraint id="basic-read-access">
        <auth-method>Basic</auth-method>
        <roles>
            <role>guests</role>
            <role>accountants</role>
        </roles>
    </security-constraint>
    <security-constraint id="sample-users">
        <auth-method>Custom</auth-method>
        <roles>
            <role>sampleusers</role>
        </roles>
    </security-constraint>
</security>

For more information about security, see Securing BlazeDS.

Creating a custom messaging adapter

You can create a custom messaging adapter for situations where you need functionality not provided by either of the standard adapters. A messaging adapter class must extend the flex.messaging.services.messaging.adapters.MessagingAdapter class. An adapter calls methods on an instance of a flex.messaging.MessageService object. Both ServiceAdapter and MessageService are included in the public BlazeDS Javadoc documentation.

The primary method of any messaging adapter class is the invoke() method, which is called when a client sends a message to a destination. In the invoke() method, you can include code to send messages to all subscribing clients or to specific clients by evaluating selector statements included with a message.

To send a message to clients, you call the MessageService.pushMessageToClients() method in your adapter's invoke() method. This method takes a message object as its first parameter. Its second parameter is a Boolean value that indicates whether to evaluate message selector statements. You can call the MessageService.sendPushMessageFromPeer() method in your adapter's invoke() method to broadcast messages to peer server nodes in a clustered environment.

package customclasspackage; 
{

    import flex.messaging.services.messaging.adapters.MessagingAdapter;
    import flex.messaging.services.MessageService;
    import flex.messaging.messages.Message;
    import flex.messaging.Destination;

    public class SimpleCustomAdapter extends MessagingAdapter {

        public Object invoke(Message message) {
            MessageService msgService = (MessageService)service;
            msgService.pushMessageToClients(message, true);
            msgService.sendPushMessageFromPeer(message, true);
            return null;
        }
    }
}

Optionally, a messaging adapter can manage its own subscriptions by overriding the ServiceAdapter.handlesSubscriptions() method and return true. You also must override the ServiceAdapter.manage() method, which is passed CommandMessages for subscribe and unsubscribe operations.

The ServiceAdapter.getAdapterState() and ServiceAdapter.setAdapterState() methods are for adapters that maintain an in-memory state that must be replicated across a cluster. When an adapter starts up, it gets a copy of that state from another cluster node when another node is running.

To use an adapter class, specify it in an adapter-definition element in the messaging-config.xml file, as the following example shows:

<adapters>
...
    adapter-definition id="cfgateway" class="foo.bar.SampleMessageAdapter"/>
...
</adapters>

Optionally, you can implement MBean component management in an adapter. This implementation lets you expose properties to a JMX server that can be used as an administration console. For more information, see Monitoring and managing services.