Skip To Content

Receive Text from a UDP Socket

The Receive Text from a UDP Socket input connector can be used to adapt event data, formatted as delimited text, received through a UDP socket connection. The delimiter between attribute values is often a comma (,), so this type of data is sometimes referred to as comma-separated values. ArcGIS GeoEvent Server can use any ASCII printable character as a delimiter to separate data attribute values.

Delimited text sent to a UDP client on port 5565.

Usage notes

Keep the following in mind when using the Receive Text from a UDP Socket input connector:

  • This input connector pairs the Text Inbound Adapter and the UDP Inbound Transport.
  • Use this input connector to receive delimited text from any UDP client able to see your server machine and connect to the specified UDP socket port.
  • By default, the connector opens a UDP socket on port 5000, however, any available server port can be used.
  • Multiple Receive Text from a UDP Socket inputs can be configured, but each must specify a unique port.
  • Multiple UDP client applications can connect and send data to a single configured input simultaneously.
  • The Message Separator parameter is required. This single character specifies the end of an event record. A newline (\n) is a common end-of-record delimiter.
  • An Attribute Separator parameter is required. This single character separates one attribute value from another. A comma (,) is a common attribute delimiter.
  • UDP datagrams are typically compact messages, and client applications may not include a message separator between messages. The Characters to Append to Each Message parameter enables an implicit message separator to be appended to each message received.
  • When the Append Source IP to Message parameter is set to Yes, the client application’s IP address and port will be appended to the datagram (message). If the character specified in the Source IP Prefix Character parameter is the same character as the character specified in the Attribute Separator parameter, the connector will interpret the appended IP and port as a string attribute value. Ensure the GeoEvent Definition includes an attribute field to accommodate the data being appended to each datagram.
  • The first attribute of a received delimited data string may be used to specify the name of a GeoEvent Definition. This is useful when datagrams with different attribute data types or numbers of data attributes are expected to be received; the data itself can help specify which GeoEvent Definition the connector should use to interpret the received data values. Use the Incoming Data Contains GeoEvent Definition parameter to leverage this capability. Typically, all data records received on a given socket will have the same schema, so this parameter should be set to No (the default).

Parameters

The following are the parameters for the Receive Text from a UDP Socket input connector:

ParameterDescription

Name

A descriptive name for the input connector used for reference in GeoEvent Manager.

Default Spatial Reference

The well-known ID (WKID) of a spatial reference to be used when a geometry is constructed from attribute field values whose coordinates are not latitude and longitude values for an assumed WGS84 geographic coordinate system, or geometry strings are received that do not include a spatial reference. A well-known text (WKT) value or the name of an attribute field containing the WKID or WKT may also be specified.

Server Port

The server port to use when establishing the UDP socket. UDP clients must be able to discover and connect to this port. The default port is 5000, but any available server port can be used.

Append Source IP to Message

Specifies whether the transport should append the IP address of the machine that sent a UDP datagram to the datagram (message). If the specified Source IP Prefix Character parameter is the same character as the Attribute Separator, the adapter interprets the appended IP and port value as an additional string attribute value. Ensure that the GeoEvent Definition includes an attribute field to accommodate the data being appended to each datagram.

  • Yes—The IP address and port a client uses to send its messages will be appended to each received event record.
  • No—Client IP address and port values will not be appended to each received event record.

Source IP Prefix Character

(Conditional)

A single literal character the transport will use to separate the IP address and port number that it is appended to each UDP datagram. Typically, the same character used as the attribute separator for the message’s principal attribute values is used so the IP address and port are appended as a new attribute; however, the IP address and port values can be joined to a final string value using a different delimiter.

The parameter is shown when Append Source IP to Message is set to Yes and is hidden when Append Source IP to Message Definition is set to No.

Characters to Append to Each Message

A single literal character the transport will append to each UDP datagram before the message’s raw byte array is sent to the adapter. UDP datagrams are normally compact messages; client applications may not include a delimiter between messages. The adapter, however, requires a message separator to indicate the end of an event data record, so if the broadcasting UDP client does not include a message delimiter, define one using the parameter.

Buffer Size (Bytes)

Specifies the size of the buffer the transport will allocate to hold raw bytes received from a broadcasting UDP client application. The default value is 2048 bytes. The buffer must be large enough to accommodate IP headers, UDP headers, attribute data values, string representations of geometry being received as data, and any data appended to each received message.

Message Separator

A single literal character that indicates the end of an event data record. Unicode values may be used to specify a character delimiter. The character should not be enclosed in quotes. A newline (\n) is a common end-of-record delimiter.

Attribute Separator

A single literal character used to separate one attribute value from another in a message. Unicode values may be used to specify a character delimiter. The character should not be enclosed in quotes. A comma is a common attribute delimiter.

Incoming Data Contains GeoEvent Definition

Specifies whether the first attribute value of each delimited line of text should be used as the name of a GeoEvent Definition. For more information, see the usage notes above.

  • Yes—The first attribute field in each event record is the name of a GeoEvent Definition (existing or new).
  • No—All the event records share a common schema and therefore share one GeoEvent Definition. The first attribute field in each event record is sensor data, not the name of a GeoEvent Definition.

Create Unrecognized Event Definitions

(Conditional)

Specifies whether a new GeoEvent Definition should be created when one with the specified name does not exist. When a delimited text file includes event records from different types of sensors, the first attribute value is used to specify the type of event and this attribute value is used as the GeoEvent Definition name.

  • Yes—A new GeoEvent Definition will be created if an event definition with the specified name does not already exist.
  • No—A new GeoEvent Definition will not be created. Inbound event data that does not have a corresponding GeoEvent Definition cannot be adapted and will not be processed.

The parameter is shown when Incoming Data Contains GeoEvent Definition is set to Yes and is hidden when set to No.

Create GeoEvent Definition

(Conditional)

Specifies whether a new or existing GeoEvent Definition should be used for the inbound event data. A GeoEvent Definition is required for GeoEvent Server to understand the inbound event data attribute fields and data types.

  • Yes—A new GeoEvent Definition will be created based on the schema of the first event record received.
  • No—A new GeoEvent Definition will not be created. Select an existing GeoEvent Definition that matches the schema of the inbound event data.

The parameter is shown when Incoming Data Contains GeoEvent Definition is set to No and is hidden when set to Yes.

GeoEvent Definition Name (New)

(Conditional)

The name assigned to a new GeoEvent Definition. If a GeoEvent Definition with the specified name already exists, the existing GeoEvent Definition will be used. The first data record received will be used to determine the expected schema of subsequent data records, a new GeoEvent Definition will be created based on that first data record's schema.

The parameter is shown when Create GeoEvent Definition is set to Yes and is hidden when set to No.

GeoEvent Definition Name (Existing)

(Conditional)

The name of an existing GeoEvent Definition to use when adapting received data to create event data for processing by a GeoEvent Service.

The parameter is shown when Create GeoEvent Definition is set to No and is hidden when set to Yes.

Construct Geometry from Fields

Specifies whether the input connector should construct a point geometry using coordinate values received as attributes. The default is No.

  • Yes—Values from specified event attribute fields will be used to construct a point geometry.
  • No—A point geometry will not be constructed. It is assumed an attribute field contains a value that can be interpreted as a geometry or the event record is nonspatial (does not have a geometry).

X Geometry Field

(Conditional)

The attribute field in the inbound event data containing the x coordinate part (for example horizontal or longitude) of a point location.

The parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No.

Y Geometry Field

(Conditional)

The attribute field in the inbound event data containing the y coordinate part (for example vertical or latitude) of a point location.

The parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No.

Z Geometry Field

(Conditional)

The name of the field in the inbound event data containing the z coordinate part (for example depth or altitude) of a point location. If left blank, the z value will be omitted and a 2D point geometry will be constructed.

The parameter is shown when Construct Geometry from Fields is set to Yes and is hidden when set to No.

Expected Date Format

The pattern used to match expected string representations of date/time values and convert them to Java Date values. The pattern's format follows the Java SimpleDateFormat class convention.

While GeoEvent Server prefers date/time values to be expressed in the ISO 8601 standard, several string representations of date/time values commonly recognized as date values can be converted to Java Date values without specifying an Expected Date Format pattern. These include the following:

  • "2019-12-31T23:59:59"—The ISO 8601 standard format
  • 1577836799000—Java Date (epoch long integer; UTC)
  • "Tue Dec 31 23:59:59 -0000 2019"—A common web services string format
  • "12/31/2019 11:59:59 PM"—Common format used in the United States (12-hour clock)
  • "12/31/2019 23:59:59"—Common format used in the United States (24-hour clock)

If the date/time values received are expressed using a convention other than one of the five shown above, you will have to specify an expected date format pattern so GeoEvent Server knows how the date/time values should be adapted.

Language for Number Formatting

The locale identifier (ID) used for locale-sensitive behavior when formatting numbers from data values. The default is the locale of the machine GeoEvent Server is installed on. For more information, see Java Supported Locales.

Multicast Mode

Specifies whether the input connector should join a multicast group to receive messages routed by an internal network to a group of intended receivers. The default is No.

  • Yes—The input connector will receive multicast packets routed to a specified group address.
  • No—The input connector will operate as a unicast (for example, point-to-point) receiver. Messages should be broadcast to the specified server port used to establish the UDP socket on the server machine running GeoEvent Server.

Multicast Group

(Conditional)

Provide the group address the input connector will join when in multicast mode. The input connector will receive packets sent to this group address. The IP address range 239.x.x.x is reserved by RFC 2365 for organization specific administrative use within a single local area network.

The parameter is shown when Multicast Mode is set to Yes and is hidden when set to No.


In this topic
  1. Usage notes
  2. Parameters