UMDS User Guide
|
UMDS includes the UMDS API, which is a library of Ultra Messaging functions for use by desktop applications. UMDS Clients communicate with the UMDS Server with TCP connections. You cannot use UDP to connect a UMDS Client to a UMDS Server.
The UMDS API is a more compact version of the Ultra Messaging API, intended to provide an easier and more consistent implementation of Ultra Messaging across enterprise desktops. The API is fully implemented for Java and .NET.
A UMDS Client application can create multiple server connections, which can be to the same UMDS Server or different UMDS Servers. The UMDS Client uses UMDS API UMDSServerConnection
class calls to establish a server connection with the following general procedure:
UMDS Client application creates a UMDSServerConnection
object.
UMDS Client application sets configuration options.
UMDS Client initiates the TCP connection.
UMDS Server confirms the connection.
UMDS Client logs into the server, and sends client configuration parameters.
UMDS Server authenticates the UMDS Client application and sets configuration parameters.
UMDS Client application creates a source or receiver, and participates in messaging functions.
After it no longer needs the connection, UMDS Client application closes sources or receivers.
You can authenticate either UMDS Client applications or individual desktop users when they connect to the server. By default, UMDS automatically authenticates all clients.
You can embed user passwords in a UMDS Client application or provide users with a login prompt. UMDS does not provide a login prompt facility. If you choose to authenticate applications or users, the application must deliver a user password to the UMDS Server with a setProperty()
call. For an example, view the example application umdssend.java
and search for svrconn.setProperty("password", password)
.
If an application or desktop user requires authentication upon connection to the UMDS Server, set the application name, user name, and password in a Basic Authentication File. UMDS formats and transmits these parameters when requesting a connection.
If your application requires different operating parameters from the UMDS Server, set the application name and parameters in a Basic Authentication File. UMDS formats and transmits these parameters when requesting a connection.
UMDS Server administrators use the application name to identify the client applications connected to the server. Application developers should coordinate their application names with the server administrator to ensure proper connections and authentication.
A UMDS Client application uses the UMDSReceiver
class to start a receiver object and subscribe to a topic. This creates a UMS proxy receiver object at the UMDS server to listen for topic messages from other Ultra Messaging applications, including other UMDS client applications. As the UMDS Server receives messages for that topic, the UMDS Server routes the message to the proper UMDS Client applications.
In the following figure, a UMDS Client application subscribes to a topic. The UMDS Client application then receives a message on the topic from a remote Ultra Messaging sending application.
A UMDS Client application uses UMDSSource.send
to send messages on a topic to the UMDS server. The UMDS server then uses a proxy source to stream these messages. You configure these sources in the umdsd Configuration File with the lbm-source
Option Type. See UMDS Topic Options.
The following figure shows a UMDS Client application sending a message to all receivers listening on the topic.
A UMDS Client send performs the following steps.
UMDSSource.send
to send a message to the UMDS Server. Clients use nonblocking sends to send messages. If the send results in an EWOULDBLOCK, the UMDS Server temporarily disables the UMDS Client send socket, which applies back pressure to the client application. The UMDS Server automatically resends the message when the Ultra Messaging source transport unblocks.
You can also write UMDS Client applications that send Immediate Messages.
UMDS clients can issue requests, and can send and receive responses, by using the UMDS client interface. UMDS clients can exchange requests and responses with other UMDS clients or with non-UMDS Ultra Messaging sources and receivers.
You cannot explicitly cancel a request issued by a UMDS client. UMDS client requests automatically time out after a server-configured period. The server-configured period applies to all clients.
The following figure shows UMDS requests and responses:
The following table describes the request and response operations shown in the preceding figure:
Operation | Description | C# and Java Method |
Request | The sending application sends a request through a UMDS source object. The request_id parameter must be a 32-bit integer. | request() |
Send Request | The UMDS server forwards the request across the UM network. | |
Request Callback | The receiver object issues a callback to the receiving application. The receipt of the callback indicates the receipt of a request. | onRequest() |
Response(s) | The receiver sends zero or more responses. | respond() |
Send Response(s) | The UMDS server forwards the response across the UM network. | n/a |
Response Callback(s) | The source object that sent the request issues one or more callbacks to the sending application. The receipt of the callbacks indicates the receipt of a response. | onResponse() |
Request Timeout | Each request has its own timeout period. When the configured timeout expires on the UMDS server, the UMDS server sends a request timeout notification to the sending client's The server sends timeout notification messages to the sending client. Therefore, if the client disconnects from the server, the client cannot receive timeout notifications. When a client disconnects, the UMDS server cancels all outstanding requests without notification. If the client reconnects, the server does not send to the client any responses or timeout notifications for the requests that the client issued before it disconnected. | onEvent() |
You can use Ultra Messaging Late Join functionality, however some aspects of Late Join work differently for UMDS Client receive applications.
With Late Join enabled, the first application that causes the UMDS Server to create a receiver for a particular topic initiates a Late Join request to the Ultra Messaging application's source for that topic. The UMDS Server also creates a message cache for the topic and stores the messages there to service subsequent late join requests more efficiently. When the UMDS Server receiver receives Late Join retransmissions, it sends them to the UMDS Client, flagged as RX messages.
When the receiver switches to live data, it streams the data to the client and continues to add to the message cache. When the message cache fills to maximum capacity, it deletes older messages as new messages arrive.
When a second UMDS Client receive application launches, it receives Late Join retransmissions from the UMDS Server message cache, not from the source's retention buffer. The second application might not receive the earlier messages that the first application received.
The following image shows how a first UMDS Client receive application receives its Late Join retransmissions from the source, while subsequent client applications receive Late Join retransmissions from the UMDS Server message cache.
There might be multiple sources on a topic, however the UMDS Server stores all messages on a topic into a single message cache. The message cache stores and dispatches data as whole messages, not message fragments.
To configure UMDS Client receiving applications to use Late Join, set the options in the umdsd configuration file. By default, Late Join is disabled for UMDS Client receive applications. The following example shows part of a umdsd configuration file that sets the options related to a UMDS Client receiving application that uses Late Join on topic orderAW
.
<topic pattern="orderAW" type="direct"> <umds-attributes> <option type="umds-receiver" name="use-late-join" value="1" /> <option type="umds-receiver" name="message-cache-size" value="10" /> <option type="lbm-receiver" name="use_late_join" value="1" /> <option type="lbm-receiver" name="late_join_info_request_interval" value="1000" /> <option type="lbm-receiver" name="late_join_info_request_maximum" value="60" /> <option type="lbm-receiver" name="retransmit_initial_sequence_number_request" value="1" /> <option type="lbm-receiver" name="retransmit_message_caching_proximity" value="2147483647" /> <option type="lbm-receiver" name="retransmit_request_interval" value="500" /> <option type="lbm-receiver" name="retransmit_request_maximum" value="0" /> <option type="lbm-receiver" name="retransmit_request_message_timeout" value="10000" /> </umds-attributes> </topic>
You can enable Late Join for UMDS sources in the same manner as for standard Ultra Messaging sources. This must be done on the UMDS server via its configuration file. The following example excerpt from a umdsd configuration file shows how to enable Late Join for topic orderAW
. The example also shows other relevant source Late Join options.
<topic pattern="orderAW" type="direct"> <umds-attributes> <option type="lbm-source" name="late_join" value="1" /> <option type="lbm-source" name="retransmit_retention_age_threshold" value="0" /> <option type="lbm-source" name="retransmit_retention_size_limit" value="25165824" /> <option type="lbm-source" name="retransmit_retention_size_threshold" value="100" /> </umds-attributes> </topic>
For more information about Late Join source configuration options, see the Ultra Messaging Configuration Guide.