You use the Producer component in a Flex application to enable the application to send messages. You can create Producer components in MXML or ActionScript.

To send a message from a Producer component to a destination, you create an mx.messaging.messages. AsyncMessage object, populate the body of the AsyncMessage object, and then call the Producer.send() method. You can create text messages and messages that contain objects.

You can optionally specify acknowledge and fault event handlers for a Producer component. An acknowledge event is dispatched when the Producer receives an acknowledge message to indicate that the destination successfully received a message that the Producer sent. A fault event is dispatched when a destination cannot successfully process a message due to a connection-, server-, or application-level failure.

For reference information about the Producer class, see Adobe LiveCycle ES ActionScript Reference.

Creating a Producer component in MXML

You use the <mx:Producer> tag to create a Producer component in MXML. The tag must contain an id value. The component typically specifies a destination that is defined in the messaging-config.xml file or the services-config.xml file. The following code shows an <mx:Producer> tag that specifies a destination and acknowledge and fault event handlers:

<?xml version="1.0"?> 
<!-- ds\messaging\CreateProducerMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.rpc.events.FaultEvent;
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;

            private function acknowledgeHandler(event:MessageAckEvent):void {
                // Handle acknowledge message event.
            }           
            
            private function faultHandler(event:MessageFaultEvent):void {
                // Handle message fault event.
            }           
                        
            // Compose the message as an instance of AsyncMessage, 
            // then use the Producer.send() method to send it.
            private function sendMessage():void {
                var message:AsyncMessage = new AsyncMessage();
                message.body = userName.text + ": " + input.text;
                producer.send(message);
            }
        ]]>
    </mx:Script>
    
    <mx:Producer id="producer"
        destination="chat"
        acknowledge="acknowledgeHandler(event);"
        fault="faultHandler(event);"/>

    <mx:TextInput id="userName"/>
    <mx:TextInput id="input"/>
    <mx:Button label="Send" 
        click="sendMessage();"/>
</mx:Application>

In this example, the Producer component sets the destination property to chat, which is a destination defined in the messaging-config.xml file. You can also specify the destination at run time by setting the destination property in your ActionScript code.

Creating a Producer component in ActionScript

You can create a Producer component in ActionScript. The following code shows a Producer component that is created in a method in an <mx:Script> tag:

<?xml version="1.0"?> 
<!-- ds\messaging\CreateProducerAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="createProducer();">

    <mx:Script>
        <![CDATA[
            import mx.messaging.*;
            import mx.messaging.messages.*;
            import mx.messaging.events.*;

            //Define a variable of type Producer.
            private var producer:Producer;

            // Create the Producer.
            private function createProducer():void {
               producer = new Producer();
               producer.destination = "chat";
               producer.addEventListener(MessageAckEvent.ACKNOWLEDGE,  acknowledgeHandler);
               producer.addEventListener(MessageFaultEvent.FAULT, faultHandler);
            }

            private function acknowledgeHandler(event:MessageAckEvent):void{
                // Handle message acknowledge event.
            }

            private function faultHandler(event:MessageFaultEvent):void{
                // Handle message fault event.
            }           

            // Compose the message as an instance of AsyncMessage, 
            // then use the Producer.send() method to send it.
            private function sendMessage():void {
                var message:AsyncMessage = new AsyncMessage();
                message.body = userName.text + ": " + input.text;
                producer.send(message);
            }            
        ]]>
    </mx:Script>    

    <mx:TextInput id="userName"/>
    <mx:TextInput id="input"/>
    <mx:Button label="Send" 
        click="sendMessage();"/>
</mx:Application>

Resending messages and timing-out requests

A Producer component sends a message once. If the delivery of a message is in doubt, the Producer component dispatches a fault event to indicate that it never received an acknowledgment from the destination. When the event is dispatched, the event handler can then make a decision to attempt to resend the message if it is safe to do so.

Two situations can trigger a fault that indicates delivery is in doubt. It can be triggered when the value of the Producer.requestTimeout property is exceeded, or the underlying message channel becomes disconnected before the acknowledgment message is received. The fault handler code can detect this scenario by inspecting the ErrorMessage.faultCode property of the associated event object for the ErrorMessage.MESSAGE_DELIVERY_IN_DOUBT value.

The Producer.connected property is set to true when the Flex client is connected to the server. The Producer.send() method automatically checks this property before attempting to send a message. Two properties control the action of the Producer component when it becomes disconnected from the server:

• reconnectAttempts

  Specifies the number of times the component attempts to reconnect to the server before dispatching a fault event. The component makes the specified number of attempts over each available channel. A value of -1 specifies to continue indefinitely and a value of zero disables attempts.

• reconnectInterval

  Specifies the interval, in milliseconds, between attempts to reconnect. Setting the value to 0 disables reconnection attempts.