Internal Listener

Some designs require that a message be passed from one process to another. For example, a process might receive a message on a protocol, process it, and then desire another listener (thread) to complete the message operation. Frequently, such messages are stored in the file system using the file emitter, and then picked up using the file listener.

As an alternative, iWay Service Manager offers the internal listener. Messages are stored in memory by the internal emitter and held until picked up by the internal listener. Messages can be made to persist in the event that the server fails or is terminated before all held messages are processed.

Each listener is associated with one internal queue that has been assigned a name. The flow that desires to store a message in the queue configures an internal emitter to that name. The listener picks up the stored messages by FIFO order, and passes them on for execution.

As the queue grows and shrinks, the internal listener can manage the listeners feeding the queue to maintain an average, desirable size. This is referred to as "rubber banding" or "back pressure." The low and high mark configuration values control this.

A common use of the internal emitter is to pass a message to one or more work flows that operate asynchronously. Each internal listener flow, for example, might update a different database or might access records from a single database based upon a computed modulus key.

As with all protocols, it is possible to either emit to the protocol following completion of the message flow or to emit immediately via an emit agent (in this case, the XDInternalEmitAgent) within the flow. If the agent approach is used, the handling of the message by the internal listener can proceed totally asynchronously with the flow that originated the message.

Once a message has been passed to an internal listener, it is separated from its originator and the originator can neither await its execution or obtain response values.

Internal Listener Properties

The following table lists and describes the internal listener properties. For instructions on creating a listener, see Configuring Listeners.

Property	Description
Name of internal queue (required)	A simple, case-sensitive name used to tie the emitter and the listener. This name must be unique to the listener, but can be specified as the destination for any number of emitters.
Persistent	If true, all documents sent to the queue by an emitter are stored on disk; at completion of the handling of the document, it is deleted.
Safestore Location	If persistent, this is the location in the file system to which documents are safestored.
Compress Persistence	If the queue is persistent, the documents written to the safestore can be compressed. The default is to not compress. Possible compressions are: fastest, smallest, general, and Huffman.
Low Mark	If the size of the named queue falls below this value from above the value, the named listeners in the Control List are sent an activate message.
High Mark	If the size of the named queue goes above this value, a passivate message is sent to the listeners in the Control List.
Control List	If a high or low mark value is crossed, the appropriate message is sent to each listed listener. For example, if two listeners LISA and LISB are feeding the internal queue, listing them as LISA,LISB will cause each to receive the appropriate message.
External Mark	When set to a number greater than 0, this causes the message to be stored in memory up to the specified number; when the queue grows larger than the specified number, the message is stored on disk. This is equivalent to splitting the memory/performance optimization for the messages in the queue, and is effective for large lists that may fill memory.
Whitespace Normalization	Specifies how the parser treats whitespace in Element content. Choose preserve to turn off all normalization as prescribed by the XML Specification.Choose condense to remove extra whitespace in pretty printed documents and for compatibility with earlier versions.
Accepts non-XML (flat) only	If true, the input data is sent directly to the business logic step. The data is not preparsed, parsed, or validated. This flag is used primarily to send non-XML to the business logic or replyTo without processing it.
Optimize Favoring	Use this option to customize how the listener performs. For smaller transactions, select performance. For large input documents that could monopolize the amount of memory used by iWay Service Manager, select memory.
Multithreading	Indicates the number of worker threads (documents or requests) that iWay Service Manager can handle in parallel. Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is still being processed. The total throughput of a system can be affected by the number of threads operating. Increasing the number of parallel operations may not necessarily improve throughput. Default: 1 Max Value: 99
Maximum Threads	Parallel threads can grow to this count automatically on demand. Over time, the worker count will decrease back to the multithreading level. Use this parameter to respond to bursts of activity.
Execution Time Limit	Maximum time that a request may take to complete. Used to prevent runaway requests. Any request that takes longer to complete than this value will be attempted to be terminated. (See the "kill interval" for related information in Global Options.)
Polling Interval	Maximum wait interval (in seconds) between checks for new requests or commands. The higher this value, the longer the interval, and the fewer system resources that are used. The side effect of a high value is that the worker thread will not be able to respond to a stop command. Default: 2.0 seconds.
Default Java File Encoding	Default encoding if incoming message is not self-declaring (that is, XML).
Agent Precedence	Sets the order by which iWay Service Manager selects agents. iWay Service Manager selects the agent or agents to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found, or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>. Possible values are <document> overrides <listener> and <listener> overrides <document>. The default value is: <document> overrides <listener>
Always reply to listener default	If true, the default reply definition is used in addition to defined reply-to and error-to destinations.
Error documents treated normally	If true, error documents are processed by any configured preemitters.
Listener is transaction manager	If true, agents run within a local transaction.
Record in Activity Log(s)	If set, activity on this channel will be recorded in the activity logs, else the activity will not be recorded.

Reference: Internal Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the Internal listener.

Name	Level	Type	Description
iwayconfig	System	String	Current active configuration name.
iwayhome	System	String	Base at which the server is loaded.
iwayworkdir	System	String	Path to base of the current configuration.
msgsize	Document	Integer	Physical length of the message payload.
name	System	String	Assigned name of the master (listener).
protocol	System	String	Protocol on which message was received.

Configuring an Internal Emitter

Messages are sent to particular destinations at the completion of a workflow. The state of the document determines which particular destination is used. The order in which the destinations are used cannot be predicted.

To route an output document or error message to a protocol other than that of the outlet (listener), you must configure an emitter. For example, an application can send input over FTP, but want to route the output to an Internal listener.

The associated emitter is used to place messages onto the internal queue. Enter the name of the queue as the destination. The queue you specify must be an Internal listener that has already been defined.

It is also possible to emit to multiple queues in a single emit operation. To do this, list the queues, separated by commas. For example, internalqueue1, internalqueue2, internalqueue3. This will emit to three queues, which are handled by three internal listeners.

Top of page

Internal Emitter Properties

The following table lists and describes the Internal emitter property. For instructions on creating an emitter, see Configuring Emitters.

Property Name	Property Description
Destination (required)	Case-sensitive name of the queue. This queue must be an internal listener that has already been defined.