Data throttling

Both BlazeDS and LiveCycle Data Services provide data throttling features that give you control over aspects of the server’s underlying messaging system.

You use data throttling to limit the number of server-to-client and client-to-server messages that a Message Service or Data Management Service destination can process per second. You can also set absolute limits for the number of client-to-server and server-to-client messages allowed per second. Without data throttling, the server pushes messages to clients without any indication on how fast the clients are processing messages. Similarly, a high number of messages from Flex clients can overwhelm a server. Throttling is useful when the server could overwhelm slow clients with a high number of messages that they cannot process or the server could be overwhelmed with messages from clients.

For server-to-client messages in LiveCycle Data Services, you can use adaptive throttling to message frequency limits based on the message processing rates of clients. You can also set policies that determine what happens to messages that exceed the specified maximum message limits.

Note: In addition to these standard throttling features, a set of advanced capabilities are available in LiveCycle Data Service only. For more information, see Advanced data tuning.

Message frequency limits

Control the rate at which a Message Service or Data Management Service destination on the server sends messages to or accepts messages from Flex clients in the following ways:

Message frequency limit

Description

Destination-level frequency

In a destination definition on the server, you can specify server-to-client and client-to-server message frequency limits in the throttle-outbound and throttle-inbound elements, respectively. There are separate settings for controlling message frequency globally and on a per-client basis.

Client-level

On the Flex client side, you can set the maxFrequency property of a Consumer, MultiTopicConsumer, or DataService component to limit the maximum number of messages that the component prefers to receive from the server. If possible, the server accommodates this setting. For MultiTopic Consumer and DataService components, which allow multiple subscriptions, you can set the maxFrequency property on a per subscription basis.

Adaptive

Advanced feature not available in BlazeDS. See Advanced data throttling.

Destination-level message frequency

You specify client-to-server and server-to-client message frequency limits for a destination in the destination’s throttle-inbound and throttle-outbound elements. Use the max-frequency attribute to set the maximum number of client-to-server or server-to-client messages per second that the destination can process. Use the max-client-frequency attribute to set the maximum number of client-to-server or server-to-client messages per second that the destination can process to or from individual clients.

The following example shows throttle-outbound and throttle-inbound elements with max-frequency and max-client-frequency attributes:

... 
<destination id="MyTopic"> 
    <properties> 
        <network> 
            <throttle-outbound policy="ERROR" 
                max-frequency="100" max-client-frequency="10"/> 
            <throttle-inbound policy="IGNORE" 
                max-frequency="100" max-client-frequency="10"/> 
...

The max-frequency attribute of the throttle-outbound element indicates that the destination sends a maximum of 100 messages per second to the entire pool of Flex clients. The max-client-frequency attribute indicates that the destination sends a maximum of ten messages per second to individual Flex clients.

The max-frequency element of the throttle-inbound element indicates that the destination processes a maximum of 100 client-to-server messages per second from the entire pool of Flex clients. The max-client-frequency attribute indicates that the destination processes a maximum of ten messages per second from individual Flex clients.

Client-level message frequency

The maxFrequency property of a client-side Consumer, MultiTopicConsumer, or DataService component lets you limit the number of messages the component receives from a destination. The server read this information and ensures that it limits the messages it sends to the maximum number of messages per second specified. The server sends up to the limit, but can send fewer messages depending on how many messages are available on the server to send. The maxFrequency property is set when the Consumer, MutiTopicConsumer, or DataService component subscribes.

The following example sets the maxFrequency property of a Consumer component that you create in ActionScript:

... 
<mx:Script> 
    <![CDATA[ 
        var consumer:Consumer = new Consumer(); 
        consumer.destination = "chat"; 
        consumer.maxFrequency = 40; 
        consumer.subscribe(); 
        ]]> 
</mx:Script> 
...

You can also set the maxFrequency property of a Consumer, MultiTopicConsumer, or DataService component that you create in MXML as the following example shows:

... 
<mx:Consumer id="consumer" destination="chat" maxFrequency="40"/> 
...

MultiTopicConsumer message frequency

Unlike the standard Consumer component, the MultiTopicConsumer component supports multiple subscriptions. You can set a default value for the maxFrequency property of a MultiTopicConsumer component, and also set separate values for individual subscriptions. The following example shows a MultiTopicConsumer with a default maxFrequency value of 40 messages per second. One of its two subscriptions uses the default value, while the other uses a different maxFrequency value specified in the third parameter of the addSubscription() method. The first two parameters of the addSubscription() method specify the subtopic and selector, respectively. The selector value is null in this case.

... 
<mx:Script> 
    <![CDATA[ 
        var consumer:MultiTopicConsumer = new MultiTopicConsumer(); 
        ... 
        consumer.maxFrequency = 40; 
        // For this subscription, use the default maxFrequency of 40. 
        consumer.addSubscription("chat.subtopic1"); 
        // Only for this subscription, overwrite the maxFrequency to 20. 
        consumer.addSubscription("chat.subtopic2", null, 20); 
        consumer.subscribe(); 
    ]]> 
</mx:Script> 
...

For more information about the MultiTopicConsumer component, see Multitopic producers and consumers.

DataService message frequency

For the DataService component, you specify the default value of the maxFrequency property as the following example shows:

... 
<mx:Script> 
    <![CDATA[ 
        ... 
        var ds:DataService = new DataService("Meeting"); 
        ds.maxFrequency = 20; 
        ... 
    ]]> 
</mx:Script> 
...

When you use a DataService component in manual routing mode (manual synchronization of messages), you can specify multiple subscriptions and subscription-level values for the maxFrequency property as the following example shows. As with the MultiTopicConsumer.addSubscription() method, the manualSync.consumerAdSubscription() method takes subtopic, selector, and maxFrequency in its three parameters.

... 
<mx:Script> 
    <![CDATA[ 
        ... 
        var ds:DataService = new DataService("Meeting"); 
        ds.autoSyncEnabled = false; 
        ds.manualSync.producerSubtopics.addItem("flex-room"); 
        // Set the subscription level frequency to 10. 
        ds.manualSync.consumerAddSubscription("flex-room", null, 10); 
        ds.manualSync.consumerSubscribe(); 
        ds.fill(…); 
        ... 
    ]]> 
</mx:Script> 
...

For more information about manual routing, see Manually routing data messages.

Adaptive client message frequency

When you enable adaptive client message frequency, the server adjusts the frequency of messages sent from server to client while taking the client’s actual message processing rate into account. You specify the maximum number of messages per second that the frequency is incrementally increased or decreased.

Add something about fact that the calculations the server does are different depending the type of endpoint you are using. For example, RTMP versus long polling AMF.

To use adaptive client message frequency, you configure the adaptive-frequency property of the flex-client-outbound-queue-processor element in the flex-client section of the services-config.xml, as follows:

  1. Set the flex-client-queue-processorclass value to "flex.messaging.client.AdvancedOutboundQueueProcessor".

  2. Set the value of the adaptive-frequency property to true.

  3. Set the value of the frequency-step-size property to the number of messages per second that you want to incrementally increase the message frequency, depending on the server’s calculation. This setting is useful when you want to gradually increase the number of messages sent per second.

    The following example shows an advanced outbound queue processor configured for adaptive message frequency:

    ... 
    <flex-client> 
        <flex-client-outbound-queue-processor 
            class="flex.messaging.client.AdvancedOutboundQueueProcessor"> 
            <properties> 
                <adaptive-frequency>true</adaptive-frequency> 
                <frequency-step-size>10</frequency-step-size> 
            </properties> 
        </flex-client-outbound-queue-processor> 
    </flex-client> 
    ...

    You can also configure an outbound queue processor for a particular endpoint in a channel definition. Such an endpoint-specific configuration overrides the global one in the services-config.xml file.

Data throttling policies

Data throttling policies determine what happens to Message Service and Data Management Service messages that exceed the specified maximum message limits.

Destinations can use the following throttling policies:

policy

Description

NONE

No data throttling is performed when the maximum message frequency is reached. This setting is equivalent to setting the maximum frequency to 0 (zero).

ERROR

Applies to client-to-server (inbound) messages only.

When the maximum frequency limit is exceeded, the server drops the message and sends an error to the client.

IGNORE

When the maximum message frequency is exceeded, the server drops the message but no error is sent to the client.

BUFFER

Advanced feature not available in BlazeDS. See Advanced data throttling.

CONFLATE

Advanced feature not available in BlazeDS.See Advanced data throttling.