The TIBCO StreamBase® Bidirectional Length Based Socket Reader Adapter was created to allow for two-way socket communication using a pair of adapters, one for reading, and one for writing. The two adapters work together by sharing the connections that are made. As the name implies the reader allows for data to be read in from one or more sockets and then converted and sent downstream as string or blob data.
The adapter allows for various forms of reading binary or string data from the socket. The options allow for reading a variable length piece of data or a fixed length piece of data. If the fixed length value is set then only that amount of data will be read from the socket and once read will be converted to a blob or string (based on schema) and output. If the fixed length is not used then a size will be read from the inbound data and parsed based on the options provided. Once the size if parsed from the inbound data, that amount of data will be read. Depending on options the size and data fields or just data are output as as a string or blob.
This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.
Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Adapter: A read-only field that shows the formal name of the adapter.
Class: A field that shows the fully qualified class name that implements the functionality of this adapter. Use this class name when loading the adapter in StreamSQL programs with the APPLY JAVA statement. You can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this adapter starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the adapter does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
| Property | Description |
|---|---|
| Port (int) | The port to use. When in server mode, this is the port to listen on. When in client mode, this is the default port to use when making new connections. |
| Server Mode (check box) | This option determines whether this adapter runs as a client (check box cleared) or as a server (check box selected). |
| Enable Control Port (check box) | This option determines whether this control port is available. The control port allows for commands to be sent to the adapter to start or stop in server mode, or to connect or disconnect in client mode. |
| Enable Status (check box) | This option enables a status port with status information about the state of the adapter during run time. Some common status tuples include connection and disconnection information. |
| Socket Identifier Field Name (string) | This required field determines the name of the field added to all outgoing data tuples. Each tuple emitted on the data output
port will contain this field with a socket identifier for the connection in the format host:port:socketidentifier, or if no socket identifier is specified for the connection, then just host:port.
|
| 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 is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. |
| Property | Description |
|---|---|
| Max Connection Count (int) | The maximum number of incoming connections that this adapter allows at any given time. If a client tries to connect when the maximum number of connections is already reached, the connection is rejected and a status tuple is emitted. |
| Connection Backlog (int) | The backlog parameter is the maximum number of pending connections on the socket. Its exact semantics are implementation specific. In particular, an implementation may impose a maximum length or may choose to ignore the parameter altogether. If the backlog parameter has the value 0, or a negative value, then an implementation specific default is used. |
| Start Server At Startup (check box) | Determines whether the adapter starts the server when the application starts. If disabled, the end-user must enable the control port and emit a command tuple to start and stop the server. |
| Property | Description |
|---|---|
| Default Host Name (string) | The default host name to connect to. This value is used when the Connect at startup value is selected or when a command tuple is received that has null for the host value. |
| Connect at startup (check box) | Determines whether the adapter connects to the default host and port when the adapter starts. |
| Reconnect Count (int) | Determines how many times this adapter will retry to connect to a host. |
| Timeout Period (int) | The number of seconds to wait to try to connect after failing to connect. |
| Property | Description |
|---|---|
| Byte Order (option) | The byte order to use when converting data. |
| Buffer Size (int) |
The size of the read or write buffer used to hold data in transition from the socket to the data transformer. If this value is too small the application will emit error messages because of a full buffer. |
| Data Field Name | The name of the String or Blob field in the output schema which will contain the data. |
| Read Length Field Name | The name of the field in the output schema which will be used to store the number of bytes read. |
| Fixed Length | The integer fixed length number of bytes to read. If this value is zero or negative it will be ignored. If this value is set all other read length parameters are ignored. |
| Read Max Length | The maximum number of bytes to read. If this value is greater than zero then if data is encountered that is large a null tuple is produced and all data is discarded. |
| Length Field Offset | The offset of the length field. |
| Length Field Length | The length of the length field. 1, 2, 3, 4, or 8 bytes for the size read at the front of the data packet |
| Length Field Adjustment | The adjustment of the length field when reading data. |
| Initial Bytes To Strip | The number of bytes to remove from the start of the byte array. |
This schema is used to define how the data is translated from byte information into a tuple.
-
Use the drop-down list to select the name of a named schema previously defined in or imported into this module. The drop-down list is empty unless you have defined or imported at least one named schema for the current module.
When you select a named schema, its fields are loaded into the schema grid, overriding any schema fields already present. Once you import a named schema, the schema grid is dimmed and can no longer be edited. To restore the ability to edit the schema grid, re-select
Private Schemafrom the drop-down list.
Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.
Caution
Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.
Use the control port to send action commands to the adapter. The adapter can be run either in server mode (where it listens for connections) or client mode (where it makes outbound connections), and each mode has its own set of commands. Tuples enqueued on this port cause the adapter to start or stop a server, or to connect or disconnect clients.
-
Command, string, the command to send to the adapter.
If the adapter is in server mode, the values are:
-
START -- This tells the adapter to start the server and listen on the specified or default host and port. Any new connection established has a
host:portkey value which outputs on each data tuple. -
STOP -- This tells the adapter to stop the server and close all client connections.
-
DISCONNECT - This tells the adapter to disconnect a client from the server. The
socketidentifermust be included and match a current connection.
If the adapter is in client mode, the values are:
-
CONNECT -- This tells the adapter to make a new connection to the specified or default host and port. The associated values
host:port:socketidentiferare used to identify this connection for further actions; those values are output as the socket identifier on all emitted data tuples. -
DISCONNECT - This tells the adapter to disconnect from the specified or default host and port. The
host:port:socketidentifercombination must match the values used to initially make the connection.
-
-
Host, string. The host to connect to. This value is only valid when sending commands to adapters in client mode. If the value is null, the default value of the adapter is used.
-
Port, int. The port to use when making connections. If the value is null the default value of the adapter is used. If the adapter is in server mode, the port value determines which port to listen on. If the adapter is in client mode, the port is used for outgoing connections.
-
SocketIdentifier (Optional), string. Only used when the adapter is in client mode. If specified, this value is added to the socket identifier value emitted on the status port as the object field with the format
Host:Port:SocketIdentifier.
The status port is used to send status information tuples downstream to inform the user of changes.
-
type, string. The type of status information emitted on this port. Status types are:
-
Connection -- Indicates this message is about a connection.
-
Server -- Indicates this message is about the listening server.
-
-
action, string.
-
Connected -- This type of action occurs when a new connection is made either as a client or server. The socket identifier will be outputted as the object of this message. For a server the socket identifier will be host:port and for clients it will be 'host:port:(optional) inputted socket identifier'
-
Disconnected -- This type of action occurs when a connection disconnects either as a client or server.
-
Failed -- A failure occurred and the failure message will be included.
-
Limit -- Used when in server mode, this message will be emitted when the max number of connections to the server has been reached.
-
Stopped -- Used when in server mode, sent when the server has been stopped.
-
Started -- Used when in server mode, sent when the server has been started.
-
-
object, string. This value may be null. If it is not null, it contains a value relevant to the status message. On new connections, this value contains the socket identifier of the new connection.
-
message, string. This is a formatted human readable message that explains the status message.
-
inputTuple. Not used for this adapter.