MqContextC_FilterApi_C_API

MqContextC - modify the data using the filter-technology …

Collaboration diagram for MqContextC_FilterApi_C_API:

MqContextC - modify the data using the filter-technology …

The filter mode is related to a special usage of the libmqmsgque software called a command pipeline. To define a filter create a server with:

• MqSetupS::isServer or IServerSetup and add a factory:
• MqFactoryC

Every filter has two context one belongs to the left command and one belongs to the right command:

 <-- left cmd --> <------- filter -------> <-- right cmd -->

                  <-- left --><- right -->
                  <- server -><- client ->
                  <- master -><- slave -->
                  <-context1-><-context2->

  ... command1   @         filter         @   command2 ...

The left context is created on application startup and the right context is created as slave of the left context.

• if the @ argument is followed by an normal command (server) a local pipeline is created:

  client @ filter @ server
  

• if the @ argument is followed by an option a non-local pipeline is created:

  <------------ host-1 -------------> <-- network --> <---------- host-2 ----------->
         <---- client arguments ---->                       <--- server arguments -->
                  <-- filter arg. -->
                    <--- options --->
  
  client @ filter @ --tcp --port 7777   ...........   server --tcp --port 7777 --fork
  

BI-DIRECTIONAL FILTER

A bi-directional filter allow a data-flow in both directions and is used in a classical client/server application:

    client ... <--> ... server

as a feature enhancement like a protocol-tunnelling:

    client @ mq2tunnel ... <--> ... tunnel2mq @ server

or to convert the protocol into an other protocol:

    client @ mq2soap ... <--> ... soap-server

To define a bi-directional filter a couple of commands provide support:

• MqServiceCreate
  • use the token +ALL to add a listener for all services. This feature is used for a tunnel to modify the body at all. (example: aguard)
• MqServiceProxy
  • use this function to link the left context with the right context identified with the slave-identifier id (default: 0). No data manipulation is performed.
• MqSlaveGetFilter, MqSlaveGetMaster, MqSlaveGetProxy
  • in a filter service the current context is used to read the data. To send the data an other context, belonging to the other site of the communication, have to be used. This function return the context of the other site.
• MqServiceTokenGet
  • if the token +ALL is used in ServiceCreate to add a generic service handler the current token is not known. This function return the current token.
• MqServiceIsTransaction
  • if the token +ALL is used in ServiceCreate to add a generic service handler the current transaction-status is not known. This function return the transaction-status as boolean with true (with-transaction) or false (without-transaction).
  • with-transaction: the package was send with MqSendEND_AND_WAIT or MqSendEND_AND_CALLBACK
  • without-transaction: the package was send with MqSendEND
• MqDumpExport
  • read and return the read-data-package as MqDumpC. Use this dump to apply a transformation to the data, like encryption (example: aguard), or to save the body in a persistent storage for later use MqDumpImport.
• MqDumpImport
  • load the MqDumpC into the read-data-package
• MqProxyForward
  • send the read-buffer or a MqDumpC, as returned by MqDumpExport, to the filter target.

ONE-DIRECTIONAL FILTER

A one-directional filter is a special form of a bi-directional filter and allow a data-flow from the left to the right.
This filter is well known from the unix shell to link different commands together:

    command1 | command2 | command3

A libmqmsgque command pipeline is created with the special character "@" instead of "|" :

    msgcmd1 @ msgcmd2 @ msgcmd3

To define a libmqmsgque filter... create a service handle with MqServiceCreate or MqServiceProxy ... using the token +FTR and +EOF

token	description
+FTR	required to act on filter data rows. Every filter input data is a list of filter data rows and every row is a list of filter data columns. Every row is send to the following filter-command as +FTR service request
+EOF	required to act on End-Of-Filter data and is called after all +FTR data was send. Sometimes the filter data can not be served as +FTR data (example: sorting of the input rows need to read all rows before the data can be send to the next filter command) and the+EOF token is used to continue send +FTR data rows.

and send every data item with MqSendEND_AND_WAIT .