Table of Contents
Just a second...

Using the ActionScript Classic API

DiffusionClient (com.pushtechnology.diffusion.DiffusionClient) is the main class that is used. This class enables the user to set all of the connection and topic information.

DiffusionClient

Connection example

import com.pushtechnology.diffusion.ServerDetails;
import com.pushtechnology.diffusion.ConnectionDetails;
import com.pushtechnology.diffusion.DiffusionClient;
import com.pushtechnology.diffusion.events.DiffusionConnectionEvent;
import com.pushtechnology.diffusion.events.DiffusionTraceEvent;
import com.pushtechnology.diffusion.events.DiffusionMessageEvent;
import com.pushtechnology.diffusion.events.DiffusionExceptionEvent;
import com.pushtechnology.diffusion.events.DiffusionPingEvent;

// Get a new DiffusionClient
var theClient:DiffusionClient = new DiffusionClient();

// Set everything to enable the cascading
var serverDetails:ServerDetails = new ServerDetails("https://diffusion.example.com:443");
var connectionDetails:ConnectionDetails = new ConnectionDetails(serverDetails, "Trade");
connectionDetails.setCascade(true);

// Add the listeners
theClient.addEventListener(DiffusionConnectionEvent.CONNECTION, onConnection);
theClient.addEventListener(DiffusionMessageEvent.MESSAGE, onMessages);
theClient.addEventListener(DiffusionTraceEvent.TRACE, onTrace);
theClient.addEventListener(DiffusionExceptionEvent.EXCEPTION, onException);
theClient.addEventListener(DiffusionPingEvent.PING, onPing);

// Connect
theClient.connect(connectionDetails);

Setting credentials

If credentials are required by the Diffusion™ server then use the setCredentials method on the DiffusionClient class. The DiffusionClientCredentials class takes a constructor argument of username and password. Please bear in mind, that these are only tokens and can contain any information that the AuthorisationHandler requires. However, if you set the username as an empty string (that is, an anonymous user) the password is not stored and you cannot retrieve it with getCredentials.

var credentials:DiffusionClientCredentials = new DiffusionClientCredentials(username, password);
theClient.setCredentials(credentials);

Connection event

The connection event contains information about the success of the connection attempt. Below is a coding example of the possibilities for the connect event.
public function onConnection(event:DiffusionConnectionEvent) : void {
	if (event.wasConnectionRejected()) {
		theClientIDBox.text = "Connection Rejected by Diffusion Server";
	} else if (event.wasClientAborted()) {
		theClientIDBox.text = "Connection aborted";
	} else if (event.isConnected()) {
		theClientIDBox.text = event.getClientID();
		theConnectedTransportLabel.text = theClient.getTransportMode();
	} else {
		theClientIDBox.text = "Connection failed " + event.getErrorMessage();
	}
}

You can receive a connection event after you have successfully connected, which might be because of a lost connection, or in the case of client aborted the Diffusion server has deliberately closed the client connection. This normally means that a publisher has aborted the connection and the client must not try and connect again.

onMessage event

When messages arrive from the Diffusion server on a subscribed topic, the DiffusionMessageEvent is dispatched. Contained in the event is a TopicMessage object TopicMessage (com.pushtechnology.diffusion.TopicMessage). This class contains helper methods that surround the message itself, like getTopic() and isInitialTopicLoad. For more information, see the API documentation.

public function onMessages(event:DiffusionMessageEvent) : void {
	var message:TopicMessage = event.getTopicMessage();
	...

Subscriptions

Once the client has connected, you can issue subscribe and unsubscribe commands. The subscribe and unsubscribe methods take a string format, that can be a topic selection pattern, a list of topics that are comma delimited or a single topic.

Send

Once connected a client can send messages to the Diffusion server on a particular topic. To do this, use the send method.

theClient.send("Fred","Hello publisher that looks after Fred");

In the example above, the publisher that looks after topic Fred receives a messageFromClient notification. If a message with user headers or encoding is required, you must use the sendTopicMessage method. A TopicMessage (com.pushtechnology.diffusion.TopicMessage) allows for the setting of user headers and message encoding

Ping

The client can ping the Diffusion server. To receive the Ping response, the listener is added to the client.

theClient.addEventListener(DiffusionPingEvent.PING, onPing);

The resulting ping event has two attributes in it, firstly the time taken to do a round trip from the client to the Diffusion server and back again. The second attribute is how many items are currently in the client queue at the server. This information enables the client to get some vital connection information. It is down to the implementation of the client to specify the ping frequency, if at all required.

Topic listeners

During the life time of the connection, it might be required to have modular components notified about topic messages – these are topic listeners. A topic listener calls a supplied function with a TopicMessage object when the topic of the message matches the pattern supplied. The topic listeners are called in the order that they are added, and before the default DiffusionMessageEvent.MESSAGE, that is called as well as the topic listener event. You can have many topic listeners on the same topic pattern if required. The function supplied in charge of processing the message can signal that a message is consumed, returning TRUE. In this case, this message is not relayed to subsequent TopicListeners and the default listener. For example, if you want to be notified about a particular topic, use the following code:

var listenerRef:String = theClient.addTopicListener("^Logs$", theLogsDataGrid.onMessage);

Note the syntax here, the ^ $ are regex pattern strings, the above means that the listener is only interested in receive the message event if the topic is Logs. If the following was issued.

var listenerRef:String = theClient.addTopicListener("Logs", theLogsDataGrid.onMessage);

Any topic name that has "Logs" in it matches. You must store the reference to remove the topic listener at a later date.

Timed topic listeners

A timed topic listener calls a supplied function with an array of topicMessage objects when the topic of the message matches the pattern, and only if the time supplied by the arguments has expired. Otherwise, the TopicMessage is stored until the time expired.

Note:

The function in charge of processing the message cannot determine if a message is consumed as you can do in a topic listener. For example, if you want to be notified about a particular topic, use the following code:

var timedListenerRef:String = theClient.addTimedTopicListener("^Logs$", theLogsDataGrid.onMessage, 2000, false);

The third parameter is the frequency at which the function supplied is called. The optional fourth parameter can be set if this function must be called, even if no messages are stored.

Failover

The ActionScript® client supports autofailover. For more information, see ActionScript failover documentation.

Special features

Paged topic data handling
Where paged topic data is in use at the server there are features within the client API which simplify the handling of messages to and from such a topic.