String
Sockets Connector Reference - Mule 4
Sockets Connector v1.2
Anypoint Connector for Sockets (Sockets Connector) provides a sockets listener, send capability, and send and receive functionality. Provides TCP and UDP requesters.
Release Notes: Sockets Connector Release Notes
Configurations
Listener Config
Config for listener sockets
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Name |
The name for this configuration. Connectors reference the configuration with this name. |
x |
||
Connection |
The connection types to provide to this configuration. |
x |
||
Expiration Policy |
Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. This does not mean that the platform expires the instance at the exact moment that it becomes eligible. Mule purges the instances as appropriate. |
Connection Types
Tcp Listener
A ConnectionProvider which provides instances of TcpListenerConnection to use by SocketListener
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Protocol |
TcpProtocol that knows how the data is read and written. If not specified, uses SafeProtocol. |
|||
TLS Configuration |
Implies the use of SSLServerSocket instead of plain TCP ServerSocket for accepting new SSL connections. |
|||
Port |
Number |
Connection’s port number |
x |
|
Host |
String |
Connection’s host name |
x |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
|||
Send Buffer Size |
Number |
The size of the buffer (in bytes) used when sending data, set on the socket itself. |
||
Receive Buffer Size |
Number |
The size of the buffer (in bytes) used when receiving data, set on the socket itself. |
||
Client Timeout |
Number |
Sets the SO_TIMEOUT value on sockets, and indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 (default) indicates waiting indefinitely. |
||
Reuse Address |
Boolean |
Sets SO_REUSEADDRESS (default) value on the sockets before binding, which helps reduce "address already in use" errors when a socket is reused. |
true |
|
Send TCP With No Delay |
Boolean |
If set, it does not collect transmitted data together for greater efficiency but sends it immediately. Defaults to true even though socket default is false, because optimizing to reduce amount of network traffic over latency is hardly ever a concern today. |
true |
|
Linger |
Number |
Sets SO_LINGER value, and indicates how long (in milliseconds) the socket takes to close, so any remaining data transmits correctly. |
||
Keep Alive |
Boolean |
Enables SO_KEEPALIVE behavior on open sockets. This automatically checks open socket connections but unused for long periods and closes them if the connection becomes unavailable. This is a property on the socket itself and a server socket uses it to control whether connections to the server keep alive before they recycle. |
false |
|
Fail On Unresolved Host |
Boolean |
Whether the socket fails during its creation if the host set on the endpoint cannot be resolved. However, set it to false to allow unresolved hosts, which is useful when connecting through a proxy. |
true |
|
Server Timeout |
Number |
Sets SO_TIMEOUT value when you use the socket as a server. The timeout that applies to the "accept" operation. If no connection arrives, a value of 0 (default) causes the accept to wait indefinitely. |
||
Receive Backlog |
Number |
The maximum queue length for incoming connections. |
50 |
UDP Listener
A ConnectionProvider which provides instances of UdpListenerConnection to use by SocketListener
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Port |
Number |
Connection’s port number |
x |
|
Host |
String |
Connection’s host name |
x |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
|||
Send Buffer Size |
Number |
The size of the buffer (in bytes) used when sending data, set on the socket itself. |
||
Receive Buffer Size |
Number |
The size of the buffer (in bytes) used when receiving data, set on the socket itself. |
||
Client Timeout |
Number |
Sets the SO_TIMEOUT value on sockets, and indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 (default) indicates waiting indefinitely. |
||
Reuse Address |
Boolean |
Sets SO_REUSEADDRESS (default) value on the sockets before binding, which helps reduce "address already in use" errors when a socket is reused. |
true |
|
Broadcast |
Boolean |
Enable or disable SO_BROADCAST value into the DatagramSocket |
false |
Request Config
Config for requester sockets
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Name |
String |
The name for this configuration. Connectors reference the configuration with this name. |
x |
|
Connection |
The connection types to provide to this configuration. |
x |
||
Expiration Policy |
Configures the minimum amount of time that a dynamic configuration instance can remain idle before Mule considers it eligible for expiration. This does not mean that the platform expires the instance at the exact moment that it becomes eligible. Mule purges the instances as appropriate. |
Connection Types
Tcp Requester
A ConnectionProvider which provides instances of TcpRequesterConnection to use by the SocketOperations
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Local Address Settings |
This configuration parameter refers to the address where the Socket should bind to. |
|||
Protocol |
TcpProtocol that knows how the data is read and written. If not specified, the SafeProtocol will be used. |
|||
TLS Configuration |
Implies the use of SSLServerSocket instead of plain TCP ServerSocket for accepting new SSL connections. |
|||
Port |
Number |
Connection’s port number |
x |
|
Host |
String |
Connection’s host name |
x |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
|||
Pooling Profile |
Characteristics of the connection pool |
|||
Send Buffer Size |
Number |
The size of the buffer (in bytes) used when sending data, set on the socket itself. |
||
Receive Buffer Size |
Number |
The size of the buffer (in bytes) used when receiving data, set on the socket itself. |
||
Client Timeout |
Number |
Sets the SO_TIMEOUT value on sockets, and indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 (default) indicates waiting indefinitely. |
||
Reuse Address |
Boolean |
Sets SO_REUSEADDRESS (default) value on the sockets before binding, which helps reduce "address already in use" errors when a socket is reused. |
true |
|
Send TCP With No Delay |
Boolean |
If set, it does not collect transmitted data together for greater efficiency but sends it immediately. Defaults to true even though socket default is false, because optimizing to reduce amount of network traffic over latency is hardly ever a concern today. |
true |
|
Linger |
Number |
Sets SO_LINGER value, and indicates how long (in milliseconds) the socket takes to close, so any remaining data transmits correctly. |
||
Keep Alive |
Boolean |
Enables SO_KEEPALIVE behavior on open sockets. This automatically checks open socket connections but unused for long periods and closes them if the connection becomes unavailable. This is a property on the socket itself and a server socket uses it to control whether connections to the server keep alive before they recycle. |
false |
|
Fail On Unresolved Host |
Boolean |
Whether the socket fails during its creation and if the host set on the endpoint cannot be resolved. However, set it to false to allow unresolved hosts, which is useful when connecting through a proxy. |
true |
|
Connection Timeout |
Number |
Number of milliseconds to wait until an outbound connection to a remote server is successfully created. Defaults to 30 seconds. |
30 |
UDP Requester
A ConnectionProvider which provides instances of UdpRequesterConnection to use by the SocketOperations
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Local Address Settings |
This configuration parameter refers to the address where the DatagramSocket should bind to. |
|||
Port |
Number |
Connection’s port number |
x |
|
Host |
String |
Connection’s host name |
x |
|
Reconnection |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
|||
Pooling Profile |
Characteristics of the connection pool |
|||
Send Buffer Size |
Number |
The size of the buffer (in bytes) used when sending data, set on the socket itself. |
||
Receive Buffer Size |
Number |
The size of the buffer (in bytes) used when receiving data, set on the socket itself. |
||
Client Timeout |
Number |
Sets the SO_TIMEOUT value on sockets, and indicates the amount of time (in milliseconds) that the socket waits in a blocking operation before failing. A value of 0 (default) indicates waiting indefinitely. |
||
Reuse Address |
Boolean |
Sets SO_REUSEADDRESS (default) value on the sockets before binding, which helps reduce "address already in use" errors when a socket is reused. |
true |
|
Broadcast |
Boolean |
Enable or disable SO_BROADCAST value into the DatagramSocket |
false |
Operations
Send
<sockets:send>
Sends the data using the client associated to the RequesterConnection.
Send And Receive
<sockets:send-and-receive>
Sends the data using the client associated to the RequesterConnection and then blocks until a response is received or the timeout is met, in which case the operation returns a null payload.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Content |
Binary |
data that will be serialized and sent through the socket. |
#[payload] |
|
Output Mime Type |
String |
The mime type of the payload that this operation outputs. |
||
Output Encoding |
String |
The encoding of the payload that this operation outputs. |
||
Streaming Strategy |
|
Configure if repeatable streams should be used and their behavior |
||
Target Variable |
String |
The name of a variable to store the operation’s output. |
||
Target Value |
String |
An expression to evaluate against the operation’s output and store the expression outcome in the target variable |
#[payload] |
|
Reconnection Strategy |
A retry strategy in case of connectivity errors |
Sources
Listener
<sockets:listener>
Listens for socket connections of the given protocol in the configured host and port. Whenever a new connection is received, this Source will schedule a SocketWorker that will handle the communication for that particular connection.
Parameters
Name | Type | Description | Default Value | Required |
---|---|---|---|---|
Configuration |
String |
The name of the configuration to use. |
x |
|
Output Mime Type |
String |
The mime type of the payload that this operation outputs. |
||
Output Encoding |
String |
The encoding of the payload that this operation outputs. |
||
Primary Node Only |
Boolean |
Whether this source should only executes on the primary node when running in a cluster |
||
Streaming Strategy |
|
Configure if repeatable streams should be used and their behavior |
||
Redelivery Policy |
Defines a policy for processing the redelivery of the same message |
|||
Reconnection Strategy |
A retry strategy in case of connectivity errors |
|||
Response Value |
Binary |
#[payload] |
Types
Tls
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Enabled Protocols |
String |
A comma-separated list of protocols enabled for this context. |
||
Enabled Cipher Suites |
String |
A comma-separated list of cipher suites enabled for this context. |
||
Trust Store |
||||
Key Store |
||||
Revocation Check |
Trust Store
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Path |
String |
The location of the trust store. This location resolves relative to the current classpath and file system, if possible. |
||
Password |
String |
The password used to protect the trust store. |
||
Type |
String |
The type of store used. |
||
Algorithm |
String |
The algorithm used by the trust store. |
||
Insecure |
Boolean |
If true, no certificate validations are performed, rendering connections vulnerable to attacks. Use at your own risk. |
Key Store
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Path |
String |
The location of the trust store. This location resolves relative to the current classpath and file system, if possible. |
||
Type |
String |
The type of store used. |
||
Alias |
String |
When the key store contains many private keys, this attribute indicates the alias of the key to use. If not defined, the first key in the file is used by default. |
||
Key Password |
String |
The password used to protect the private key. |
||
Password |
String |
The password used to protect the key store. |
||
Algorithm |
String |
The algorithm used by the key store. |
Standard Revocation Check
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Only End Entities |
Boolean |
Only verify the last element of the certificate chain. |
||
Prefer Crls |
Boolean |
Try CRL instead of OCSP first. |
||
No Fallback |
Boolean |
Do not use the secondary checking method. |
||
Soft Fail |
Boolean |
Avoid verification failure when the revocation server can not be reached or is busy. |
Custom Ocsp Responder
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Url |
String |
The URL of the OCSP responder. |
||
Cert Alias |
String |
Alias of the signing certificate for the OCSP response (must be in the trust store), if present. |
Reconnection
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Fails Deployment |
Boolean |
When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy. |
||
Reconnection Strategy |
The reconnection strategy to use. |
Reconnect
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect |
||
Count |
Number |
How many reconnection attempts to make. |
Reconnect Forever
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Frequency |
Number |
How often in milliseconds to reconnect |
Expiration Policy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Idle Time |
Number |
A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration |
||
Time Unit |
Enumeration, one of:
|
A time unit that qualifies the maxIdleTime attribute |
Immutable Socket Attributes
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Port |
Number |
x |
||
Host Address |
String |
x |
||
Host Name |
String |
x |
||
Local Certificates |
Array of Any |
The SSL local certificates. If the Socket is not an SSL Sockets, this is null. |
||
Peer Certificates |
Array of Any |
The SSL peer certificates. If the Socket is not an SSL Sockets, this is null. |
Repeatable In Memory Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Initial Buffer Size |
Number |
The allocated amount of memory to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then the buffer expands according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize. |
||
Buffer Size Increment |
Number |
This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer does not expand, and STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full. |
||
Max Buffer Size |
Number |
The maximum amount of memory to use. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower than or equal to zero means no limit. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which all these attributes are expressed |
Repeatable File Store Stream
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
In Memory Size |
Number |
Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed content on the disk is buffered. |
||
Buffer Unit |
Enumeration, one of:
|
The unit in which maxInMemorySize is expressed |
Redelivery Policy
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Redelivery Count |
Number |
The maximum number of times a message can be redelivered and processed unsuccessfully before triggering process-failed-message |
||
Use Secure Hash |
Boolean |
Whether to use a secure hash algorithm to identify a redelivered message. |
||
Message Digest Algorithm |
String |
The secure hashing algorithm to use. If not set, defaults to SHA-256. |
||
Id Expression |
String |
Defines one or more expressions to use to determine when a message is redelivered. This property may only be set if useSecureHash is false. |
||
Object Store |
Object Store |
The object store to store the redelivery counter for each message. |
Socket Connection Settings
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Port |
Number |
Connection’s port number |
x |
|
Host |
String |
Connection’s host name |
x |
Pooling Profile
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Active |
Number |
Controls the maximum number of Mule components that can be borrowed from a session at one time. When set to a negative value, there is no limit to the number of components that can be active at one time. When maxActive is exceeded, the pool exhausts. |
||
Max Idle |
Number |
Controls the maximum number of Mule components that can sit idle in the pool at any time. When set to a negative value, there is no limit to the number of Mule components that can be idle at one time. |
||
Max Wait |
Number |
Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the exhaustedAction is set to WHEN_EXHAUSTED_WAIT. |
||
Min Eviction Millis |
Number |
Determines the minimum amount of time an object may sit idle in the pool before it is eligible for eviction. When nonpositive, no objects will be evicted from the pool due to idle time alone. |
||
Eviction Check Interval Millis |
Number |
Specifies the number of milliseconds between runs of the object evictor. When non-positive, no object evictor is executed. |
||
Exhausted Action |
Enumeration, one of:
|
Specifies the behavior of the Mule component pool when the pool is exhausted. Possible values are: WHEN_EXHAUSTED_FAIL, which throws a NoSuchElementException, WHEN_EXHAUSTED_WAIT, which blocks by invoking Object.wait(long) until a new or idle object is available, or WHEN_EXHAUSTED_GROW, which creates a new Mule instance and return it, essentially making maxActive meaningless. If a positive maxWait value is supplied, it blocks for at most that many milliseconds, after which a NoSuchElementException will be thrown. If maxThreadWait is a negative value, it blocks indefinitely. |
||
Initialisation Policy |
Enumeration, one of:
|
Determines how components in a pool can initialize. The possible values are INITIALISE_NONE does not load any components into the pool on startup, INITIALISE_ONE loads one initial component into the pool on startup, or INITIALISE_ALL loads all components in the pool on startup |
||
Disabled |
Boolean |
Whether pooling should be disabled |
Safe Protocol
This test protocol precedes every message with a cookie, and should not be used in production environments.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Message Length |
Number |
Indicates the maximum length of the message. |
-1 |
|
Encoding |
String |
Indicates the encoding used for serializing the cookie |
||
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
Direct Protocol
This protocol allows the socket to read until no more bytes are immediately available. On slow networks, EOFProtocol
and LengthProtocol
might be more reliable.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
Length Protocol
This protocol is defined by sending or reading an integer (the packet length) and then the data to transfer.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Max Message Length |
Number |
Indicates the maximum length of the message. |
-1 |
|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
Streaming Protocol
This protocol allows the socket’s Send operation to return a message with the original InputStream as payload.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
XML Message Protocol
This protocol reads streaming XML documents. The only requirement is that each document includes an XML declaration at the beginning of the document in the form of <?xml….
.
Data is read until a new document is found or until there is no more currently available data. For slower networks, XmlMessageEofProtocol
might be more reliable.
Also, because the default character encoding for Anypoint Platform is used to decode the message bytes when looking for the XML declaration, some caution with message character encodings is warranted.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
XML Message Eof Protocol
This protocol extends XmlMessageProtocol
to continue reading until either a new message or EOF is found.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
Custom Protocol
Define your own custom protocol by writing a class that extends TcpProtocol
.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Class |
String |
Reference to full qualifier class name that should extend TcpProtocol to use as a custom protocol |
x |
Eof Protocol
When clients connect to a server using the EOF protocol, they write the message on the socket connection output stream. To signal the end of the message, clients must signal the end of file (EOF) by closing the output stream and keeping the input stream open, waiting for a response from the server. This behavior is known as half-close. Then, the server sends a response and closes its output stream and the whole socket connection.
For TLS secured connections, use TLS 1.3 and JDK 11 as the half-close feature is not supported in TLS 1.2 and earlier versions. The half-close feature triggers the close notification alert to prevent TLS truncation attacks. JDK 11 and newer versions support TLS 1.3. Also, pooling profile is not compatible with EofProtocol
.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |
Custom Class Loading Length Protocol
A length protocol that uses a specific class loader to load objects from streams.
Field | Type | Description | Default Value | Required |
---|---|---|---|---|
Class Loader |
Any |
|||
Max Message Length |
Number |
Indicates the maximum length of the message. |
-1 |
|
Rethrow Exception On Read |
Boolean |
Indicates if the exception should be rethrown if there is a failure while reading |
false |