Contents
The TIBCO StreamBase® Input Adapter for UDP is an embedded adapter that receives raw string data by listening on a UDP port. It resembles the CSV Socket Reader adapter.
Unlike the CSV Socket Reader adapter, though, this socket adapter reads input data from a UDP socket with no associated connection IP address. Also, since the data sent through the UDP socket is represented as simple strings, this adapter has no formatting properties (such as 'field delimiter' or 'string quote character').
In Multicast Mode (described below), the UDP socket is specifically a Multicast socket and does have an IP address associated with its Multicast Group. This group can consist of many members, who are all capable of receiving messages sent to the group. Furthermore, any address can send messages to the group, not just other members.
N.B.: This adapter will truncate any received packet greater than 1024 bytes long.
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 |
|---|---|---|
| Receive Port | This is the communication port number to which the UDP socket binds. It also serves to help identify the multicast group, when in multicast mode. | 9000 |
| Mode | If checked, the adapter will join the specified multicast group and only receive messages sent to that group | Unchecked |
| Port Reuse | This is an advanced option, applicable only when in unicast mode. It allows multiple UDPReceivers (or in general, UDP Sockets)to be bound to the same port on the same machine. All of the UDPReceivers (and any unicast mode UDPSenders)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 |
| Multicast Group | The hostname or IP address which is used, along with the port number, to identify the multicast group. Valid multicast IP addresses range from 224.0.0.1 to 239.255.255.255, inclusive. | 239.0.0.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 |
| Max Packet Size (bytes) | The maximum size in bytes of the packet that can be received. | 1024 |
| 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 |
Typechecking fails in the following circumstances:
-
An illegal receive 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.
On suspend, this adapter closes its input socket and, if in multicast mode, leaves the multicast group.
On resumption, it reconnects its socket, rejoins the group (if in multicast mode) and continues reading tuples from it.
This adapter does not leave its socket open during suspend primarily so that the port which it is bound to will be freed for other use while it is suspended. Unlike the CSV Socket Reader, this socket is UDP and thus will simply drop incoming packets if it is connected and suspended; there would be no buffering or memory issues.
-
Control (input#1): 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 and close its connection to the socket. Any tuples sent to that group while the socket is disconnected will not be received. This socket can be reconnected with the 'connect' command.
-
connect
This command will reconnect the socket and rejoin the multicast group, when it has been 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.
-
-
Data (output #1): This is the primary output port, through which strings received via the multicast connection will output tuples.
The schema for this port will have three fields:
-
"Payload" , <string>
This is the contents of the payload of the packet, as represented by a string.
-
"SenderIP" , <string>
The physical IP address of the sender of the packet, in the form "XXX.XXX.XXX.XXX"
-
"SenderPort" , <int>
The port on which the process which sent this packet is operating
-
-
Status (output): 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. In addition, it will have a message, timestamp and in some cases the tuple that caused the status report.
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.
In Multicast Mode, the paradigm is that this adapter (and perhaps others) will be reporting messages to a group of many receiving adapters.
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 external multicast traffic.
Multicast Mode will cause several changes in behavior from the normal, unicast mode.
In Multicast Mode, the paradigm is that this adapter will subscribe to a multicast group, and receive any messages sent to that group's IP and Port.
In either mode, messages can be received from any sender, via UDP protocol, on the specified Port.
Multiple Multicast Sockets may be bound to the same port on the same machine, thus multiple UDP Receiver adapters may be bound to the same Port if in multicast mode. If they are in unicast mode, then the Port Reuse option must be checked to bind multiple Receivers to the same port.
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.