Contact Us 1-800-596-4880
  1. Homepage
  2. Sockets Connector (1.2)

  3. Sockets Connector Reference

All Connectors

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

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

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

One of:

TcpProtocol that knows how the data is read and written. If not specified, uses SafeProtocol.

TLS Configuration

Tls

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

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

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

Associated Sources

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

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

Socket Connection Settings

This configuration parameter refers to the address where the Socket should bind to.

Protocol

One of:

TcpProtocol that knows how the data is read and written. If not specified, the SafeProtocol will be used.

TLS Configuration

Tls

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

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

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

Socket Connection 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

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

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

Supported Operations

Operations

Send

<sockets:send>

Sends the data using the client associated to the RequesterConnection.

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]

Reconnection Strategy

A retry strategy in case of connectivity errors

For Configurations

Throws

  • SOCKETS:UNKNOWN_HOST

  • SOCKETS:CONNECTIVITY

  • SOCKETS:CONNECTION_TIMEOUT

  • SOCKETS:RETRY_EXHAUSTED

  • SOCKETS:LENGTH_EXCEEDED

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

Output

Type

Binary

Attributes Type

Immutable Socket Attributes

For Configurations

Throws

  • SOCKETS:UNKNOWN_HOST

  • SOCKETS:CONNECTIVITY

  • SOCKETS:CONNECTION_TIMEOUT

  • SOCKETS:RETRY_EXHAUSTED

  • SOCKETS:LENGTH_EXCEEDED

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

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]

Output

Type

Binary

Attributes Type

Immutable Socket Attributes

For Configurations

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

Trust Store

Key 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.

Crl File

Field Type Description Default Value Required

Path

String

The path to the CRL file.

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:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

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:

  • BYTE

  • KB

  • MB

  • GB

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:

  • BYTE

  • KB

  • MB

  • GB

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:

  • WHEN_EXHAUSTED_GROW

  • WHEN_EXHAUSTED_WAIT

  • WHEN_EXHAUSTED_FAIL

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:

  • INITIALISE_NONE

  • INITIALISE_ONE

  • INITIALISE_ALL

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

See Also

Back to top
View on GitHub