Contents
The TIBCO StreamBase® Output Adapter for UDP is an embedded adapter that writes string data through a socket to another machine or process. It resembles the CSV Socket Writer adapter. Unlike the CSV Socket Writer adapter, though, this socket adapter writes output data to a UDP socket instead of a TCP socket.
When in multicast mode, the adapter will send messages to a multicast group. All listening members of the group will receive messages sent by this adapter.
N.B.: There is no maximum packet size, however if this is being used in conjunction with the UDP Receiver, then only the first 1024 bytes of the message will be received, as that adapter has a packet size limitation.
In addition, UDP is an unreliable protocol where messages may be dropped or received out of order, your application should keep this in mind; larger packets may introduce more unreliability.
| Property | Description | Default |
|---|---|---|
| Port | The UDP port to which this adapter binds locally. This is not the same as the port to which outgoing messages are sent. | 9999 |
| Multicast Mode | If this is checked, the adapter will send messages to the specified multicast group, instead of sending to the address and port supplied on its input port. | Unchecked |
| Multicast Group | The host name or IP address which identifies the target multicast group. | 239.0.0.0 |
| Multicast Port | The UDP port used to identify the multicast group. | 9000 |
| Use Default Charset | Use the default character set for your machine. | Checked |
| Charset | The name of the character set to use, if Use Default Charset is Unchecked. | None |
| Reconnect Count | The number of times the adapter should try to reconnect to the socket should the connection fail. 0 means attempt to reconnect indefinitely. | 0 |
| Use Default Charset | Use the default character set for your machine. | Checked |
| Charset |
The name of the character set to use, if Use Default
Charset is unchecked.
|
None |
| Connect on Startup |
If checked, the adapter creates the UDP socket during start-up. Otherwise,
the socket can be created after start-up by enqueuing a tuple to the control
port with a command field value of connect.
|
Checked |
| Log Level | Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. | INFO |
| Port Reuse | This is an advanced option, applicable only when in unicast mode. It allows multiple UDPSenders (or in general, UDP Sockets)to be bound to the same port on the same machine. All of the UDPSenders (and any unicast mode UDPReceivers)must have this option checked for them to be able to bind to that port. Similarly, general UDP Sockets must set the SO_REUSEADDR socket option. This may not work on all systems. | Unchecked |
Typechecking fails in the following circumstances:
-
An illegal port number is specified.
-
The specified multicast group IP address or host name does not resolve to a multicast address, if configured for multicast mode.
-
Use Default Charset is unchecked and the Charset name provided is not supported.
-
The schema of the control input port is missing the required
commandfield or contains extraneous fields. -
The schema of the data input port is missing required fields, has fields of the wrong type, or contains extraneous fields.
-
Data (input #1): This is the primary input port, any tuples enqueued on this port will be sent as messages. The required schema for this port will differ depending on whether or not the adapter is in multicast mode.
If not in multicast mode, the required schema will be as follows (the fields may have arbitrary names):
-
First field , <string>
This is the contents of the payload of the packet, as represented by a string.
-
Second field , <string>
The physical IP address of the sender of the packet, in the form "nnn.nnn.nnn.nnn"
-
Third Field , <int>
The port on which the process which sent this packet is operating
If in multicast mode, the required input schema has the form:
-
First field , <string>
This is the contents of the payload of the packet, as represented by a string.
As you can see, the first field requirement is the same, regardless of mode.
-
-
Control (input#2): The input schema for this port must have its first field be of type 'string' and have the name 'command'. When a valid command tuple is enqueued on this port, the adapter will execute the command directive.
The valid commands are as follows:
-
disconnect
This will cause the adapter to leave the multicast group (if in multicast mode) and close its connection to the socket. Any tuples enqueued while the socket is disconnected will not be sent. This socket can be reconnected with the 'connect' command.
-
connect
This command will reconnect the socket and rejoin the multicast group (if in multicast mode), if it had been previously disconnected by the 'disconnect' command. In the event of connection failure and automatic retry failure, this command will not properly reconnect the socket, a restart is required in that instance.
-
status
This command will cause the adapter to output a status tuple detailing the current connection status.
-
-
Status (output#1): This is a secondary output port, through which the adapter will output status tuples. Each status tuple will have a 'TYPE' and an 'ACTION', which will describe the current status.
The 'TYPES' and their associated 'ACTIONS' follow:
-
Data Status
This is used for when an error occurs while trying to parse or output data within Streambase. This will always be paired with the 'Error' action.
-
Connection Status
This is used for any connection related status messages, and can have the actions: 'Connected' or 'Disconnected'
-
Command Status
This is used to confirm or deny the success of a command, entered through the control port. The associated actions are: 'Error', 'Connected' , 'Disconnected'.
-
Suspend/Resume
This status be emitted whenever the adapter has either been suspended or is about to resume operation. It will either have the action 'Suspended' or 'Resuming'
-
Multicast Mode causes several changes in behavior from the default, unicast mode.
First, it changes the required input schema (see UDP Sender Ports).
In Multicast Mode, the paradigm is that many receiving adapters receive messages sent to the group.
The members of the group may change, but the IP and Port identifying this group are fixed. Thus, it doesn't make sense to communicate the recipient's host and port through input tuple fields.
Multiple Multicast Sockets may be bound to the same port on the same machine, so that multiple UDP Sender adapters can be bound to the same port, if in multicast mode; else they must have the "Port Reuse" option checked.
Note
Many firewalls do not allow multicast communication, to prevent overloading the network with traffic. You may need to adjust your firewall settings accordingly. It is recommended that you allow internal multicast communication only, unless otherwise necessary, to prevent receiving unwanted multicast traffic from outside.
Multicast Mode will cause several changes in behavior from the normal, unicast mode.
First of all, it will change the required input schema (see UDP Sender Ports).
In Multicast Mode, the paradigm is that this adapter (and perhaps others) will be reporting messages to a group of many receiving adapters.
The members of that group may change, but the IP and Port identifying this group are fixed; thus it no longer makes sense to communicate the IP and Port of the recipient in the EventFlow
Multiple Multicast Sockets may be bound to the same port on the same machine, thus multiple UDP Sender adapters can be bound to the same port, if in multicast mode; else they must have the "Port Reuse" option checked.
N.B. Many firewalls do not allow multicast communication, to prevent overloading the network with traffic. You will likely have to adjust your firewall settings accordingly; it is recommended that you limit this to allow internal multicast communication only, unless otherwise necessary, to prevent receiving unwanted outside multicast traffic.