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” on page 106.
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:
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: 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.
... <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” on page 205.
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> ...
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.
Deserialization validators
You can validate AMF and AMFX deserialization of client-to-server messages when you create an instance of a Java class and set the values of the object’s properties. Validation lets you ensure that the server creates only specific types of objects and that only specific values are allowed on an object’s properties.
Using deserialization validators
Deserialization validator classes must implement the flex.messaging.validators.DeserializationValidator interface, which contains the following methods:
• boolean validateCreation(Class<?> c), which validates the creation of a class.
• boolean validateAssignment(Object instance, int index, Object value), which validates the assignment of a value to an index of an Array or List instance.
• boolean validateAssignment(Object instance, String propertyName, Object value), which validates the assignment of a property of an instance of a class to a value.
For more information about the DeserializionValidator interface, see the LiveCycle Data Services Javadoc documentation.
Note: If a deserialization validator maintains internal state, guard access and modification of that state with a lock.
There is a single deserialization validator per message broker and multiple threads could access the same validator.
You can assign deserialization validators at the top level of the services-config.xml file, as the following example shows: <?xml version="1.0" encoding="UTF-8"?> <services-config> ... <validators> <validator class="mycompany.myvalidators.TestDeserializationValidator"/> </validators> ... </services-config>
You can also use the runtime configuration feature to dynamically create deserialization validators in a bootstrap service class at server startup. Create a MessageBroker and a validator instance in a Java class, and then call the MessageBroker’s setDeserializationValidator() method to use the validator. The following example shows this approach:
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” on
page109.
CONFLATE Advanced feature not available in BlazeDS.See “Advanced data throttling” on
page109.
...
MessageBroker broker = MessageBroker.get MessageBroker(null);
TestDeserializationValidator validator = new TestDeserializationValidator(); validator.
// Next, you can call specific add/remove methods on the validator // for allowed/disallowed classes.
...
broker.setDeserializationValidator(validator); ...
The default validator, flex.messaging.validators.ClassDeserializationValidator, lets you explicitly allow or disallow specific class types. For more information about this class, see the LiveCycle Data Services Javadoc documentation. To use the ClassDerializationValidator, you specify disallowed and allowed classes within disallow-classes and allow-classes elements as the following example shows. You can use fully qualified class names or wildcard expressions in class name values.
<?xml version="1.0" encoding="UTF-8"?> <services-config> ... <validators> <validator class="flex.messaging.validators.ClassDeserializationValidator"> <properties> <disallow-classes> </disallow-classes> <allow-classes> <class name="java.*"/> <class name="\[Ljava.*"/> <class name="flex.*"/> <class name="\[B*"/> </allow-classes> </properties> </validator> </validators> ... </services-config>
To help determine which class types are deserialized on the server, you can use the sample
features.validators.deserialization.ClassLoggingDeserializationValidator class. Registering this validator in a development environment lets you capture to the server log all required types that the application uses. When a class is encountered for the first time, an info-level log message that lists the class name is printed to the
Endpoint.Deserialization.Creation log category. By default, log messages are sent to the console. You can use this information to configure a ClassDeserializationValidator instance that disallows creation of all non-required types in the production environment.
The source code for the ClassLoggingDeserialization class is in the resources/samples/validators directory of your LiveCycle Data Services installation. Unlike the ClassSerializationValidator validator, the configuration for this validator does not use any properties. You only need to specify the class name of the validator in a validator element. For more information about the DeserializionValidator interface, see the LiveCycle Data Services Javadoc
documentation. More Help topics
Advanced data tuning
LiveCycle Data Services provides a set of advanced data tuning features that give you greater control over the server’s data delivery capabilities.
Note: Advanced data tuning features are not available in BlazeDS. Advanced data tuning includes the following features:
Advanced messaging support
To use most advanced data tuning features, you enable advanced messaging support on the server. The AdvancedMessagingSupport service enables reliable messaging support as the server starts up and handles interactions with client-side AdvancedChannelSet objects at runtime.
The following example shows the text you must add to the services section of the services-config.xml file: ... <services> ... <service id="AdvancedMessagingSupport" class="flex.messaging.services.AdvancedMessagingSupport"/> ... </services> ...
Suppose you have MXML applications in which you create ChannelSet objects manually and you want to use the listed advanced data tuning features. In this case, modify your applications to use the AdvancedChannelSet class in the fds.swc file rather than the base ChannelSet class in the rpc.swc file.
The following example shows the difference between using the standard ChannelSet object and the AdvancedChannelSet object:
...
// Existing base ChannelSet.
var channelSet:ChannelSet = new ChannelSet(); ...
// New AdvancedChannelSet.
var channelSet:ChannelSet = new AdvancedChannelSet(); ...
Feature Description
Reliable messaging Improves the quality of message delivery between Flex clients and the LiveCycle Data
Services server. For more information, see “Reliable messaging” on page107.
Advanced data throttling
Includes adaptive throttling and the BUFFER and CONFLATE throttling policies. For more
information, see “Advanced data throttling” on page109.
Message priority Lets you set the priority of server-to-client messages when using the Message Service or
Data Management Service. For more information, see “Message priority” on page111.
Message filtering Lets you pre-process incoming messages and post-process reply messages and pushed
Reliable messaging
The reliable messaging feature improves the quality of message delivery between clients and destinations on the LiveCycle Data Services server.
Reliable messaging provides the following benefits above what is provided with standard messaging:
Note: To use reliable messaging, you enable advanced messaging support.
To enable reliable messaging, you set the reliable property to true in the network properties section of the destination definition, as the following example shows:
... <destination id="trade-settlement"> <properties> <network> <reliable>true</reliable> </network> </properties> </destination> ...
By default, if a channel was successfully connected before experiencing a fault or disconnection, it attempts a pinned reconnection to the same endpoint URL once. If this immediate reconnection attempt fails, the channel falls back to its previous failover strategy and attempts to fail over to other server nodes in the cluster or fall back to alternate channel protocols. To support IP mobility use cases, the AdvancedChannelSet object provides the following property that you can assign in ActionScript code to extend the time duration for reliable reconnect attempts to continue. One such use case is undocking a laptop and waiting several seconds for its wireless modem to start up and acquire network connectivity and a new IP address.
advancedChannelSet.reliableReconnectDuration = 60000; // In milliseconds. Benefit Description
No message loss No messages are lost when transient network failures occur if the AdvancedChannelSet
object's immediate reliable reconnect attempt succeeds.
If this single attempt fails the reliable sequence is closed and the client proceed to regular channel failover and channel set hunting.
Ordered message delivery
Reliable messaging ensures the delivery of correctly ordered messages when using AMF or HTTP channels/endpoints that use more than one TCP socket concurrently to send or receive messages. Message order is ensured even if the intended order differs from the order in which the messages are received from the network.
When you use RTMP channels/endpoints, messages are delivered in the correct order whether you use reliable messaging.
No duplicate message processing
There is no duplicate processing of messages even when messages for reliable destination are automatically sent following a disconnect and reconnect.
Reconnection to server following unexpected connection loss
For deployments where network connections are forced to close periodically, reliable messaging allows the client to seamlessly reconnect to the same server. The client resumes exactly where it left off, as long as the server has not crashed, or exited.
A single reliable reconnection is attempted immediately following connection loss. This reconnection attempt allows the reliable connection to survive due to an idle timeout or when firewalls, proxies, or other network components force a TCP connection to close periodically. If this single attempt fails, the reliable sequence is closed and the client proceeds to regular channel failover and channel set hunting. The feature currently does not support repeated reliable reconnect attempts.
The default value is 0. The default behavior is to try a single, immediate reliable reconnection. By assigning a value larger than 0, you give the AdvancedChannelSet more time to attempt to reconnect reliably more than once. You can also set this value statically in the services-config.xml file within the flex-client section, as the following example shows:
...
<flex-client>
<reliable-reconnect-duration-millis>60000</reliable-reconnect-duration-millis>
<!-- Idle timeout for FlexClient state at the server, including reliable messaging sequences. In order to support reliable reconnects consistently across all supported channels and endpoints, this value must be defined and greater than 0.
Note: Any active sessions/connections keep idle FlexClient instances alive. This timeout only applies to instances that have no currently active associated sessions/connections. -->
<timeout-minutes>1</timeout-minutes> </flex-client>
...
Note: If you do not define an explicit FlexClient timeoutand at least one RTMP endpoint is registered with the message
broker, the server uses a default timeout of 5 seconds for FlexClient timeout. This allows reliable messaging over RTMP to work with no configuration other than setting destinations as reliable. If you want to use a longer reliable reconnect interval, use the optional timeout-minutes and reliable-reconnect-duration-millis elements within the