| Name | StatelessController |
| Classname | org.jumpi.impl.controller.stateless.StatelessController
|
| Description | The StatelessController provides a transparent Controller functionality, where messages are passed between client application and Connector layer without any flow control, concurrency support, ordering nor quality of service guarantees. Messages are handled opaquely, subject only to optional send transformation on send, and receive transformation when received. Any number of Connectors are supported. A message is sent to or received from a single Connector, which is the first to support the Destination's Url, determined in configuration order. Supports any Destination Url syntax which the Connectors support.
|
| Url Syntax | The Destination Urls supported are those of the configured Connectors, without alteration.
|
| Compatibility | Essentially compatible with all Connectors, however since no concurrency or synchronization support is provided, it is the responsibility of the client application to make sure the concurrency and synchronization requirements of the Connection components used are met. For example if a Connector does not support multiple concurrent sends to the same Destination, then this must be guaranteed by the client application.
|
| Configuration |
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- connector
- instancelist - mandatory. A list of comma separated component name suffixes of Connectors to instantiate and link to the Controller.
|
| Send Operation |
| Description | Send the message to the Destination, providing no flow control, quality of service guarantees, ordering nor concurrency support. No message delivery guarantees are implemented over and above those provided by the Connector layer. Send operations are delegated to a single Connector which created the Destination in getDestination(). The StatelessController passes the message directly to the Connector after performing optional send transformation on the message. There is a 1:1 relationship between calls to send and those passed down to the Connector layer.
|
| Transformation | The message format required on entry is not defined since messages are handled as opaque objects, subject to send transformation once before passing to the Connector layer.
|
| Concurrency | Potentially allows unlimited multiple concurrent send operations to the same Destination and different Destinations. Concurrency may be limited at the Connector layer.
Concurrent operations are allowed. |
| Synchronization | Blocking or non blocking depending on the synchronization of the send method of the Connector. No synchronization nor flow control takes place in the Controller. The caller's thread is used to delegate to the Connection layer. Therefore send may block if the Connector's send method blocks. If the Connector's send method is synchronous, then the method only returns once the send has completed at the Connector.
|
| Recv Operation |
| Description | Receive a message from the Destination, providing no quality of service guarantees, ordering nor concurrency support. Receive operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to receive and those passed down to the Connector layer.
|
| Transformation | The message format required on receive is not defined since messages are handled as opaque objects, subjected to receive transformation before passing to the client application in the Handle.
|
| Concurrency | Potentially allows unlimited multiple concurrent receive operations to the same Destination and different Destinations. Concurrency may be limited at the Connector layer.
Concurrent operations are allowed. |
| Synchronization | Blocking or non blocking depending on the synchronization of the receive method of the Connector. The caller's thread is used to delegate to the Connection layer. Therefore receive may block if the Connector's receive method blocks. If the Connector's receive method is synchronous, then the method only returns once the receive has completed at the Connector.
|
| Name | SequentialController |
| Classname | org.jumpi.impl.controller.ordering.SequentialController
|
| Description | The SequentialController enforces single send and single receive operation concurrency over all the Connectors. A client application will block when submitting new send or receive operations when there is an operation already pending completion. The pending operation must complete or be cancelled before any new operations are processed. Any number of Connectors are supported. A message is sent to or received from a single Connector, which is the first to support the Destination's Url, determined in configuration order. Supports any Destination Url syntax which the Connectors support.
|
| Url Syntax | The Destination Urls supported are those of the configured Connectors, without alteration.
|
| Compatibility | Essentially compatible with all Connectors. Since sends and receives are strictly serialized over all Connectors, it may be more efficient to use the OrderingController to achieve serialization on a per Connector basis.
|
| Configuration |
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- connector
- instancelist - mandatory. A list of comma separated component name suffixes of Connectors to instantiate and link to the Controller.
|
| Send Operation |
| Description | Send the message to the Destination. Send operations are serialized over all Connectors. If more than one send is issued by the client application, then the additional operations are blocked. It is not defined in which order blocked operations are unblocked. This is determined by the VM's thread notification. No message delivery guarantees are implemented over and above those provided by the Connector layer. Send operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to send and those passed down to the Connector layer.
|
| Transformation | The message format required on entry is not defined since messages are handled as opaque objects, subject to send transformation once before passing to the Connector.
|
| Concurrency | Only one send operation can be handled at a time, irrespective of the Connector. Multiple sends are blocked until they can be handled.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | Blocking or non blocking depending on the synchronization of the send method of the Connector. The caller's thread is used to delegate to the Connection layer. Therefore send may block if the Connector's send method blocks. If the Connector's send method is synchronous, then the method only returns once the send has completed at the Connector.
|
| Recv Operation |
| Description | Receive a message from the Destination. Receive operations are serialized over all Connectors. If more than one receive is issued by the client applicaction, then the additional operations are blocked. It is not defined in which order blocked operations are unblocked. This is determined by the VM's thread notification. Receive operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to receive and those passed down to the Connector layer.
|
| Transformation | The message format required on entry is not defined since messages are handled as opaque objects, subject to receive transformation once before passing to the client application in the Handle.
|
| Concurrency | Only one receive operation can be handled at a time, irrespective of the Connector. Multiple receives are blocked until they can be handled.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | Blocking or non blocking depending on the synchronization of the receive method of the Connector. The caller's thread is used to delegate to the Connection layer. Therefore recv may block if the Connector's recv method blocks. If the Connector's recv method is synchronous, then the method only returns once the recv has completed at the Connector.
|
| Name | OrderingController |
| Classname | org.jumpi.impl.controller.ordering.OrderingController
|
| Description | The OrderingController enforces single send and single receive operation concurrency for each Destination. Submitting multiple sends or receives to a single Destination will cause the operations to be queued and processed in order. Any number of Connectors are supported. A message is sent to or received from a single Connector, which is the first to support the Destination's Url, determined in configuration order. Supports any Destination Url syntax which the Connectors support. The OrderingController maintains a cache of state per Destination. This is cleaned up at configurable timer intervals. The state per Destination contains a send and a receive pending queue for ordering operations. The cache size is also configurable.
|
| Url Syntax | The Destination Urls supported are those of the configured Connectors, without alteration.
|
| Compatibility | Compatible with Connectors which have either single operation per Destination or multiple operation per Destination concurrency. Care must be taken with Connectors which only support a single send or receive operation irrespective of Destination, since this is not enforced by the OrderingController.
|
| Configuration |
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- connector
- instancelist - mandatory. A list of comma separated component name suffixes of Connectors to instantiate and link to the Controller.
- maxrecvsperdestination
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of pending receives for a single Destination before blocking further receive operations for that Destination.
- maxsendsperdestination
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of pending sends for a single Destination before blocking further send operations for that Destination.
- cleanupinterval
- integer - optional [1000
..MAX-INT
] def[10000
]. The time interval in milliseconds between cache cleanups.
- statecachesize
- integer - optional [10
..MAX-INT
] def[50
]. The initial size of the state cache. The cache size is not fixed, so sizing this correctly will simply avoid unnecessary container size changes at runtime.
|
| Send Operation |
| Description | Send a message to a Destination. Send operations are serialized for each Destination. Send operations for separate Destinations are handled concurrently. Send operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to send and those passed down to the Connector layer.
|
| Transformation | The message format required on entry is not defined since messages are handled as opaque objects, subject to send transformation once before passing to the Connector layer.
|
| Concurrency | Send operations to multiple Destinations are handled concurrently, and also multiple send operations to the same Destination.
Concurrent operations are allowed. |
| Synchronization | Blocking or non blocking depending on the synchronization of the send method of the Connector and whether there are already pending sends waiting to be sent to the Connector. If there are already pending sends, the send operation is queued and the caller returns immediately unless the limit to the pending send queue has been reached. If the Connector's send method is synchronous then the Controller's send is also synchronous since the calling thread is used to delegate to the Connector. In completing the send at the Connector, the callbackSend causes queued sends to be sent to the Connector in a recursive fashion. Therefore if send operations are continually placed in the send queue then there is the danger of Stack overflow due to too deep recursion with the synchronous sending Controller. Therefore it is advisable to use the OrderingController only with asynchronous Connectors. If the Connector's send method is asynchronous, then the Controller's send method is also asynchronous. The calling thread drives the send operation to the Connector, but it is the Connector's asynchronous completion of the operation which drives further pending operations.
|
| Recv Operation |
| Description | Receive a message from the Destination. Receive operations are serialized for each Destination. Receive operations for seperate Destinations are handled concurrently. Receive operations are delegated to a single Connector which created the Destination in getDestination(). There is a 1:1 relationship between calls to receive and those passed down to the Connector layer.
|
| Transformation | The message format required on entry is not defined since messages are handled as opaque objects, subject to receive transformation once before passing to the client application in the Handle.
|
| Concurrency | Receive operations to multiple Destinations are handled concurrently, and also multiple receive operations to the same Destination.
Concurrent operations are allowed. |
| Synchronization | Blocking or non blocking depending on the synchronization of the receive method of the Connector and whether there are already pending receives waiting to be sent to the Connector. If there are already pending receives, the receive operation is queued and the caller returns immediately unless the limit to the pending receive queue has been reached. If the Connector's recv method is synchronous then the Controller's recv is also synchronous since the calling thread is used to delegate to the Connector. In completing the receive at the Connector, the callbackRecv causes queued receives to be sent to the Connector in a recursive fashion. Therefore if receive operations are continually placed in the receive queue then there is the danger of Stack overflow due to too deep recursion with the synchronous receiving Controller. Therefore it is advisable to use the OrderingController only with asynchronous Connectors. If the Connector's recv method is asynchronous, then the Controller's recv method is also asynchronous. The calling thread drives the receive operation to the Connector, but it is the Connector's asynchronous completion of the operation which drives further pending operations.
|
| Name | DummyAsyncConnector |
| Classname | org.jumpi.impl.connector.dummy.DummyAsyncConnector
|
| Description | The DummyAsyncConnector simulates asynchronous send and receive operations without actually performing the operations on the network layer. This can be helpful for testing purposes. Send and receive operations handled sequentially by a separate thread from the caller. The caller returns immediately on send or receive unless flow control kicks in. There is a configurable delay to simulate real network transmission times. This delay can be modified on a per operation basis with the respective operation's client properties.
|
| Url Syntax | <protocolname>://[*]
|
| Url Syntax | <protocol>://<uri> where <protocol> is the configured protocol and <uri> is any string.
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- senddelay
- integer - optional [0
..MAX-INT
] def[0
]. The default time interval to delay the sending thread to simulate a real send.
- recvdelay
- integer - optional [0
..MAX-INT
] def[0
]. The default time interval to delay a receiving thread to simulate a real receive.
|
| Send Operation |
| Description | Simulate sending a message asynchronously to a Destination, providing configurable send delay and failure opportunity.
|
| Transformation | The message format required on entry is determined by the send transformer. Since messages are not actually sent, the Connector does not require any specific message format.
|
| Concurrency | Allows multiple concurrent send operations to the same Destination and different Destinations. The sends are however processes sequentially by the instance's task working off the buffered send queue.
Concurrent operations are allowed. |
| Synchronization | The operation is asynchronous. Non blocking until the buffered send queue has filled, at which time send flow control prohibits further sending until there is space in the queue.
|
| Customization |
- PROPERTY_FAIL
- any - optional. If the PROPERTY_FAIL is present, the operation will fail after the delay.
- PROPERTY_DELAY
- integer - optional. If the PROPERTY_DELAY is present, it overrides the time delay in milliseconds that has been configured to simulate network operations for the operation.
|
| Recv Operation |
| Description | Simulate receiving a message asynchronously from a Destination, providing configurable receive delay and failure opportunity. Since no actual message is received from the network layer, the client application can provide a message to return and a sender. In the absence of the client application specifying these values, defaults are provided.
|
| Transformation | The message format required on reception is determined by the receive transformer. Since messages are not actually received, the receive transformer must handle the default message type, which is a String, or the type passed as the received message in the client properties.
|
| Concurrency | Allows multiple concurrent receive operations to the same Destination and different Destinations. The receives are however processes sequentially by the instance's task working off the buffered receive queue.
Concurrent operations are allowed. |
| Synchronization | The operation is asynchronous. Non blocking until the buffered receive queue has filled, at which time receive flow control prohibits further receives until there is space in the queue.
|
| Customization |
- PROPERTY_FAIL
- any - optional. If the PROPERTY_FAIL is present, the operation will fail after the operation delay.
- PROPERTY_DELAY
- integer - optional. If the PROPERTY_DELAY is present, it overrides the time delay in milliseconds that has been configured to simulate network operations for the operation.
- PROPERTY_RECV_MESSAGE
- any - optional. If the PROPERTY_RECV_MESSAGE is present, it will be used as the message received. If it is not present, then a default String message is received.
- PROPERTY_RECV_SENDER
- string - optional. If the PROPERTY_RECV_SENDER is present, it will be used as the Url of the sender. If it is not present, then a default String Url is used as the Sender Url.
|
| Name | LoopbackConnector |
| Classname | org.jumpi.impl.connector.loopback.LoopbackConnector
|
| Description | The LoopbackConnector simulates a loopback network adapter where sends are passed straight back to receives without actually performing the operations on the network layer. This can be helpful for testing purposes. There is a configurable send delay for simulating network delays.
|
| Url Syntax | <protocol>://<uri> where <protocol> is the configured protocol and <uri> is any string. The <uri> value *; represents a wildcard, matching any other <uri;>
|
| Configuration |
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- connector
- instancelist - mandatory. A list of comma separated component name suffixes of Connectors to instantiate and link to the Controller.
- senddelay
- integer - optional [0
..MAX-INT
] def[0
]. The default time interval to delay the sending thread to simulate a real send.
|
| Send Operation |
| Description | Send a message asynchronously to a receiver on the Destination, providing configurable send delay. If no receiver is registered on the Destination at the time of sending, then the send will fail. The message is not sent over any network. Illegal to send to the wildcard Destination, since this is not a real Destination.
|
| Transformation | The message format required on entry is determined by the send transformer. The transformed message is passed unchanged by value to the receiver.
|
| Concurrency | Allows multiple concurrent send operations to the same Destination and different Destinations. The sends are however processes sequentially by the instance's task working off the buffered send queue.
Concurrent operations are allowed. |
| Synchronization | The operation is asynchronous. Non blocking until the buffered send queue has filled, at which time send flow control prohibits further sending until there is space in the queue.
|
| Recv Operation |
| Description | Receive a message asynchronously from a Destination. The receive operations are registered in two tables. One table for specific Destinations, and the other for the wildcard Destination. A send operation matching a registered receive will be passed back to the receiver. A send operation matching no receive operation will fail.
|
| Transformation | The message format required on reception is determined by the receive transformer.
|
| Concurrency | Allows concurrent receive operations to different Destinations, yet only a single receive operation to each Destination.
Concurrent operations are not allowed at a single Destination, but operations at different Destinations can be performed concurrently. Violating the concurrency requirement results in the operation failing. |
| Synchronization | The operation is asynchronous. Non blocking always.
|
| Name | MpiConnector |
| Classname | org.jumpi.impl.connector.mpi11.MpiConnector
|
| Description | The MpiConnector allows to send and receive messages via mpiJava over a native MPI1.1 implementation. Currently a single Group, COMM_WORLD is established and intra-group, point to point communications are allowed. A client application must ensure that receive's are matched by send's in order to avoid blocking. A configurable but fixed sized receive buffer is used to receive messages. Truncation occurs if the buffer length is exceeded on receive.
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- args
- commaseparatedstrings - optional def[
]. The comma separated arguments to pass to MPI.Init call to bootstrap the MPI implementation.
- sendbuflen
- integer - optional [0
..MAX-INT
] def[8192
]. The initial size of the send buffer in bytes. The send buffer grows if more data is written to it, but it never shrinks. The receive buffer does not grow so in order to avoid data truncation, pre-determined data sizes are required.
- recvbuflen
- integer - optional [0
..MAX-INT
] def[8192
]. The receive buffer size in bytes. The receive buffer does not grow so in order to avoid data truncation, pre-determined data sizes are required.
|
| Send Operation |
| Description | Send a message to a MPI Processor Destination.
|
| Transformation | The message format required at the native MPI layer is a byte[]. If a send transformer is configured, then the transformer must transform the message Object into a byte[] and place this in the send buffer. The send buffer is pushed onto the envelope's context stack on top of the message itself. If no send transformer is configured, then the message must be a byte[].
|
| Concurrency | Allows only a single send at a time, blocking if multiple sends are performed concurrently.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. The default MPI send mode is used. This is typically blocking.
|
| Recv Operation |
| Description | Receive a message from a MPI Processor Destination. Receiving from the MPI Connector Destination ( <protocol>:// ) returns the MPI COMM_WORLD GroupMembershipInfo structure. From this, the client application can address send and receive operations to specific MPI Processors. A receive from any processor is achieved by calling recv on the Group's wildcard destination.
|
| Transformation | The receive operation at the MPI layer delivers a byte[]. Tbe byte[] is read by the MPIConnector into the receive buffer. If the sent data is more than the size of the receive buffer, then the data is truncated. The length may be less than the size of the receive buffer. If a receive transformer is configured, then this must transform the receive buffer's contents. The receive operation's status and then the receive buffer are placed on the context stack. If no receive transformer is defined, then the receive buffer's byte[] is passed up to the controller layer. A subsequent receive will overwrite the receive buffer's contents.
|
| Concurrency | Allows only a single receive at a time, blocking if multiple receives are performed concurrently.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. The default MPI receive mode is used. This is typically blocking.
|
| Name | UdpConnector |
| Classname | org.jumpi.impl.connector.udp.UdpConnector
|
| Description | The UdpConnector sends and receives packets over unicast UDP. A UdpTransceiver instance continuously receives packets from a local configured port. Receive operations define a Destination filter through which packets must match before being dispatched to the Controller layer. If packets are received where no receive Destination is defined, then the packet is simply discarded. Wildcard destinations are used to match any host, any port or the combination of both. Sending can take place to any UdpDestination.
|
| Url Syntax | <protocolname>://[<ipaddress>|*]:[<port>|*]
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- transceiver
- instance - optional def[default + org.jumpi.impl.connector.udp.UdpTransceiver
]. The transceiver subcomponent's name suffix.
UdpTransceiver
- datagramsize
- integer - optional [0
..MAX-INT
] def[65536
]. The receive buffer size in bytes which limits the size of incoming packets. Should correspond to the Udp packet size on the network.
- port
- integer - optional [0
..MAX-INT
] def[8888
]. The Udp port on which to establish a continuous listener and send packets from.
- readtimeout
- integer - optional [1000
..MAX-INT
] def[30000
]. The datagram socket read timeout in milliseconds. Maximum time interval that the reading thread will be stuck in the socket's read call if there is nothing to receive.
- address
- string - optional. The local address to use if this is to be different from the localhost address. Used to determine the network card to use on multi-homed hosts.
|
| Send Operation |
| Description | Send a message to a UdpDestination.
|
| Transformation | The message format required for sending via the UdpTransceiver is a byte[]. If a send transformer is configured then this must map the input data to a byte[], otherwise the byte[] must be supplied by the Controller. The UdpTransceiver does not modify the data for sending via Udp at all. The operation may fail or truncate data if the length of the data is greater than that which can be sent by the operating system.
|
| Concurrency | Allows multiple concurrent send operations to any Destinations. The sends are processes sequentially by the instance's task working off the buffered send queue.
Concurrent operations are allowed. |
| Synchronization | The operation is asynchronous. Non blocking until the buffered send queue has filled, at which time send flow control prohibits further sending until there is space in the queue.
|
| Recv Operation |
| Description | Receive a message from a UdpDestination. The UdpDestination of the receive is placed in a UdpDestination filter. When the UdpTransceiver receives a DatagramPacket which matches the UdpDestination, this will be passed up as the response to the receive operation. For best performance, use specific UdpDestinations without wildcards, or few wildcard Destinations.
|
| Transformation | The format of the data provided by the UdpTransceiver is a byte[]. This is given directly as the received data to the Controller in absence of a receive transformer. If a receive transformer is configured, then this is given the byte[] and it gives the transformed message to the Controller layer.
|
| Concurrency | Allows multiple concurrent receive operations to different Destinations but not the same Destination. There is no limit to the number of different Destinations which can simultaneously be received from.
Concurrent operations are not allowed at a single Destination, but operations at different Destinations can be performed concurrently. Violating the concurrency requirement results in the operation failing. |
| Synchronization | The operation is asynchronous. Non blocking always.
|
| Name | TcpConnector |
| Classname | org.jumpi.impl.connector.tcp.TcpConnector
|
| Description | The TcpConnector provides unreliable messaging guarrantees over TCP. A TcpConnection is established per TcpDestination on send. TcpConnections are maintained in a connection cache and reused for subsequent sends. TcpConnections may be closed when the connection cache is full or when the connection timeout has expired without any send or receive activity taking place. Each TcpConnection has a dedicated Thread which reads data continuously from the remote peer and dispatches the data to the TcpConnector. If data is read and there is no receive operation registered at the TcpConnector, then the data is discarded. Therefore the TcpConnector is not strictly reliable, eventhough TCP provides a certain amount of "reliability". True reliability can anyway only be provided by an acknowledgement functionality at a higher layer. This non blocking, lossy, reception property on the otherhand avoids distributed deadlock. If send or receive failure occurs, then the TcpConnection is closed and the matching operation is failed. Receives on wildcard destinations are used to match incoming data on any host, any port or the combination of both.
|
| Url Syntax | <protocolname>://[<ipaddress>|*]:[<port>|*]
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- cleanupinterval
- integer - optional [1000
..MAX-INT
] def[60000
]. The interval in milliseconds between TcpConnection cache cleanups.
- connectiontimeout
- integer - optional [1000
..MAX-INT
] def[30000
]. The TcpConnection timeout interval in milliseconds. A timed-out connection is always closed during cache cleanup.
- flowcontroltimeout
- integer - optional [-1
..MAX-INT
] def[60000
]. The maximum time in milliseconds that a TcpConnection can delay receiving subsequent messages from it's Socket because a matching receive is not posted. If a TcpConnection cannot pass its received message on to the TcpConnector within this time period, then the message is lost with a warning. The timeout should be greater than the maximum processing time for messages received to avoid message loss. -1 means infinite timeout, 0 - no timeout, positive is finite timeout.
- servermode
- boolean - optional def[false
]. If servermode is true then send operations do not automatically create TcpConnections to the TcpDestination addressed. Send operations are assumed to be replies to previous received messages, which should have already a TcpConnection established. Sends which do not have active TcpConnections associated to the Destination are failed immediately. If servermode is true, then the acceptor must be set also.
- cachesize
- integer - optional [1
..MAX-INT
] def[100
]. The size of the TcpConnection cache. The number of active connections is reduced to the cache size at each cleanup interval.
- acceptor
- instance - optional. The acceptor subcomponent's name suffix. If servermode is true, then this must be set.
- maxmessagesize
- integer - optional [0
..MAX-INT
] def[10000000
]. The maximum message size allowed on send.
- maxconnections
- integer - optional [0
..MAX-INT
] def[200
]. The maximum number of active connections allowed.
- socketreadtimeout
- integer - optional [0
..MAX-INT
] def[30000
]. The socket read timeout value in milliseconds.
- socketlinger
- integer - optional [0
..MAX-INT
] def[0
]. The socket linger timeout value in milliseconds.
- socketnodelay
- boolean - optional def[false
]. The socket no delay value.
- socketkeepalive
- boolean - optional def[false
]. The socket keep alive value.
TcpConnectionAcceptor
- timeout
- integer - optional [1000
..MAX-INT
] def[30000
]. The server socket accept timeout in milliseconds. Maximum time interval that the accepting thread will be stuck in the socket's accept call if there are no new connection attempts.
- port
- integer - optional [0
..MAX-INT
] def[8888
]. The server socket port.
- backlog
- integer - optional [0
..MAX-INT
] def[10
]. The server socket backlog. The number of unaccepted connections, pending aception, which can be buffered by the operating system.
- address
- string - optional. The local address to use if this is to be different from the localhost address. Used to determine the network card to use on multi-homed hosts.
|
| Send Operation |
| Description | Send a message to a TcpDestination over a TcpConnection. If a TcpConnection exists in the connection cache, then this is used to send the data. If there is no TcpConnection, and the servermode is not set, a TcpConnection is established to the remote peer.
|
| Transformation | The message format required for sending via the TcpConnection is a byte[]. If a send transformer is configured then this must map the input data to a byte[], otherwise the byte[] must be supplied by the Controller. The TcpConnection wraps the data to be sent into a packet. The data length must be less than the configured maximum for sending.
|
| Concurrency | Allows multiple concurrent send operations to any Destinations. The sends are processes sequentially by the instance's task working off the buffered send queue.
Concurrent operations are allowed. |
| Synchronization | The operation is asynchronous. Non blocking until the buffered send queue has filled, at which time send flow control prohibits further sending until there is space in the queue.
|
| Recv Operation |
| Description | Receive a message from a TcpDestination. The TcpDestination to receive from is included in a filter. When a TcpConnection receives data and the TcpConnection's remote peer TcpDestination matches this entry, then the data will be passed up as the response to the receive operation. Wildcard receives may only be used to match the first message from a remote peer, since until a single message is received, the client layer does not know the sender's address. This is since the local port number of the sender is determined dynamically when establishing the TcpConnection when sending. A receive from a specific TcpDestination will fail immediately if there is no TcpConnection established to the remote peer. When a TcpConnection breaks and there is a receive operation pending for that remote peer, then the receive operation fails.
|
| Transformation | The format of the data provided by the TcpConnection is a byte[]. This is given directly as the received data to the Controller in absence of a receive transformer. If a receive transformer is configured, then this is given the byte[] and it gives the transformed message to the Controller layer.
|
| Concurrency | Allows multiple concurrent receive operations to different Destinations but not the same Destination. There is no limit to the number of different Destinations which can simultaneously be received from.
Concurrent operations are not allowed at a single Destination, but operations at different Destinations can be performed concurrently. Violating the concurrency requirement results in the operation failing. |
| Synchronization | The operation is asynchronous. Non blocking always.
|
| Name | JmsConnector |
| Classname | org.jumpi.impl.connector.jms10.JmsConnector
|
| Description | The JmsConnector allows message sending and receiving via a third-party JMS provider. The JmsConnector is JMS provider agnostic and uses portable client JMS code, using JNDI lookups for ConnectionFactories and Destinations. The JmsConnector uses separate JNDI Contexts for Topic and Queues. One QueueConnection and one TopicConnection are created on demand for messaging in the point-to-point or publish-subscribe domain respectively. Messaging to separate JmsDestinations is performed in separate JMS Sessions. One JMS Producer is created per JmsDestination to perform message sending. One JMS Consumer is created per JmsDestination to preform message receiving. Send receive and request reply messaging is possible.
|
| Url Syntax | <protocolname>://topic|queue:<name>
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- queuejndikey<N>
- string - optional. The key for the N-th JNDI InitialContext's property for Queues. The value is the property queuejndivalue<N>.
- queuejndivalue<N>
- string - optional. The value for the N-th JNDI InitialContext's property for Queues. The value is the property queuejndikey<N>.
- topicjndikey<N>
- string - optional. The key for the N-th JNDI InitialContext's property for Topics. The value is the property topicjndivalue<N>.
- topicjndivalue<N>
- string - optional. The value for the N-th JNDI InitialContext's property for Topics. The value is the property topicjndikey<N>.
- jndiqueueconnectionfactorylookup
- string - optional def[QueueConnectionFactory
]. The value used to lookup the QueueConnectionFactory in JNDI for the single JMS Connection used for point-to-point messaging.
- jnditopicconnectionfactorylookup
- string - optional def[TopicConnectionFactory
]. The value used to lookup the TopicConnectionFactory in JNDI for the single JMS Connection used for publish subscribe messaging.
|
| Send Operation |
| Description | Send a message to a JMS Destination.
|
| Transformation | The message format passed over JMS is an ObjectMessage. The ObjectMessage payload is simply a serializable Object. Transformation of the message to send by the send transformer is optional.
|
| Concurrency | Allows multiple concurrent send operations to different Destinations but not the same Destination.
Concurrent operations are not allowed at a single Destination, but operations at different Destinations can be performed concurrently. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. The JMS provider's send operation may or may not be truly asynchronous. The send is considered complete on the synchronous return from the JMS provider's send or publish call. This may block due to flow control in the JMS provider.
|
| Customization |
- PROPERTY_JMS_CORRELATION_ID
- string - optional. The PROPERTY_JMS_CORRELATION_ID is used to enable correlation of reply messages with request messages. The property is transferred unchanged to the JMS Message's JMSCorrelationID.
- PROPERTY_JMS_TTL
- string - optional. The PROPERTY_JMS_TTL is the time-to-live in milliseconds for sent messages. If not set, messages never expire.
- PROPERTY_JMS_REPLY_WANTED
- any - optional. The PROPERTY_JMS_REPLY_WANTED is an indicator that the sender is a requestor and will perform a receive on the Destination returned in the PROPERTY_JMS_REPLY_DESTINATION which is returned in the send operation's Handle's properties. The JmsConnector creates a Temporary JMS Destination which is set as the JMS Message's JMSReplyTo Destination. Use the PROPERTY_JMS_CORRELATION_ID to give the replyer a correlation id to use on the reply, so the requestor can uniquely receive the reply.
|
| Recv Operation |
| Description | Receive a message from a JMS Destination. The time to block in the receive is configurable. If the JMS Message received was sent with a correlation id, then this is provided to the client layer in the Handle's properties called PROPERTY_JMS_CORRELATION_ID. If the JMS Message received has a JMSReplyTo Destination set for replying, then this Destination is returned to the client layer in the Handle's sender. If no JMSReplyTo is set on the received message then the receive Destination is the Sender.
|
| Transformation | The receive operation at the JMS layer delivers expects ObjectMessages. If a receive transformer is configured, then this must transform the ObjectMessage.
|
| Concurrency | Allows multiple concurrent recv operations to different Destinations but not the same Destination.
Concurrent operations are not allowed at a single Destination, but operations at different Destinations can be performed concurrently. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. The JMS provider's receive operation is synchronous, blocking for at most for the period defined in the PROPERTY_JMS_RECEIVE_TIMEOUT. The receive is considered complete on the synchronous return from the JMS provider's receive call. If a receive timeout happens, then the receive operation is failed.
|
| Customization |
- PROPERTY_JMS_RECEIVE_TIMEOUT
- string - optional. The PROPERTY_JMS_RECEIVE_TIMEOUT is the time in milliseconds for the receive to block without receiving a message. If not set, receives block forever.
- PROPERTY_JMS_CORRELATION_ID
- string - optional. The PROPERTY_JMS_CORRELATION_ID is used to enable correlation of reply messages with request messages. The JMS Message's JMSCorrelationID must match the given property for a receive to be matched. Unmatched received messages are simply discarded!
|
| Name | EmailConnector |
| Classname | org.jumpi.impl.connector.email.EmailConnector
|
| Description | The EmailConnector allows to send and receive E-mail messages.
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- jointestinterval
- integer - optional [1000
..MAX-INT
] def[1000
]. The time in milliseconds to check if the controller has finished during shutdown.
- joinfailinterval
- integer - optional [$jointestinterval
..MAX-INT
] def[30000
]. The time in milliseconds to before shutdown must complete, regardless if the controller are still running.
- maxsendbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered send operations before blocking the caller for new send operations.
- maxrecvbacklog
- integer - optional [1
..MAX-INT
] def[10
]. The maximum number of buffered recv operations before blocking the caller for new recv operations.
- smtphost
- string - optional def[localhost
]. The SMTP hostname where there the SMTP server resides for sending messages.
- defaultfrom
- string - optional def[nooneCnowhere
]. The default from email address if none is provided on send.
- accessprotocol
- string - optional def[none
]. The protocol to use in accessing an email account - none, imap or pop3. If none is chosen, then no email reception is possible, and the host, username and password parameters are not used.
- accesshost
- string - optional def[none
]. The host to access via the accessprotocol. Only required if accessprotocol is not none.
- username
- string - optional def[none
]. The imap or pop3 account username. Only required if accessprotocol is not none.
- password
- string - optional def[none
]. The imap or pop3 account password. Only required if accessprotocol is not none.
- inboxname
- string - optional def[Inbox
]. The folder name of the imap or pop3 account folder from which to receive email messages. Only required if accessprotocol is not none.
- autodelete
- boolean - optional def[true
]. Whether to automatically delete messages which have been passed up to the client layer and retrieved from the email account. If false, the client layer itself must call javax.mail.Message.setFlag(Flags.Flag.DELETED,true) on the message received, so that it is not received multiple times on subsequent polls from the email account. Setting to false gives additional robustness, such that the client can guarrantee that the mail is only deleted AFTER it is processed, but at the expense of additional client layer coding.
- pollinterval
- integer - optional [10000
..MAX-INT
] def[30000
]. The time in milliseconds to between successive polls of the email account for new messages. Polling takes place only when all received messages have been read.
|
| Send Operation |
| Description | Send an email Message.
|
| Transformation | The message format required at the EmailConnector layer is either a MimeMessage or simply a String. If a send transformer is configured, then the transformer must transform the message Object into a MimeMessage or a String, and place onto the envelope's context stack.
|
| Concurrency | Allows only a single send at a time, blocking if multiple sends are performed concurrently.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. This operation may block if the underlying java mail send blocks.
|
| Customization |
- PROPERTY_EMAIL_SUBJECT
- string - optional. The PROPERTY_EMAIL_SUBJECT is the subject text, overriding any MimeMessage subject if sending with a MimeMessage.
|
| Recv Operation |
| Description | Receive an email Message from an Email account.
|
| Transformation | The receive operation delivers a javax.mail.Message object.
|
| Concurrency | Allows only a single receive at a time, blocking if multiple receives are performed concurrently.
Concurrent operations are not allowed regardless of the Destination. Violating the concurrency requirement results in the caller blocking until the requirement is satisfied. |
| Synchronization | The operation is synchronous. Blocks until an unread email is received from the email account.
|
| Name | HttpConnector |
| Classname | org.jumpi.impl.connector.midp10.http.HttpConnector
|
| Description | The HttpConnector allows synchronous message sending and receiving via a Midp10 HttpConnection using HTTP-POST. A message format sent and received is a Hashtable of String key-value pairs. Hashtable messages are translated into HTTP-POST requests where the content is UTF-8 encoded plain text, where each key and value are separated by a linefeed ( 0x0a ). The Hashtable values should not contain linefeeds since no linefeed escaping is used. The synchronous response message to the HTTP-POST is expected also to be UTF-8 encoded plain text, where each key and value are separated by a linefeed. The response is converted to a Hashtable and is made availible for the receive call by the Midlet.
|
| Url Syntax | <protocolname>://<uri>
|
| Configuration |
- protocol
- string - mandatory. The protocol which this connector supports.
- sendtransformer
- string - optional. The classname of a transformer to transform data once per send. If not set, data is not transformed on send.
- recvtransformer
- string - optional. The classname of a transformer to transform data upon reception. If not set, data is not transformed on receive.
- maxlength
- integer - optional [0
..MAX-INT
] def[1024
]. The maximum number of bytes which may be received as the POST response. Any data in excess of the maximum length is discarded.
|
| Send Operation |
| Description | Send a message to an HttpDestination. A HttpConnection is established for each message sent. The message data is POSTed as line separated plain text to the HttpDestination's URL. The message response is received synchronously after the send, although a Jumpi client application must use recv() to get the response which is buffered. The buffered response is overwritten on each send() and cleared on recv().
|
| Transformation | The message format expected is a Hashtable of String key-value pairs. The values should not contain linefeeds, since linefeeds are used in the line encoding of the HTTP POST data, to separate keys and values. If a send transformer is used, the transformation must result in a Hashtable.
|
| Concurrency | Allows only one send/recv operation at a time regardless of Destination. A send operation must be followed by a receive operation to the same Destination in order to pickup the synchronous response.
Concurrent operations are not allowed regardless of the Destination. |
| Synchronization | The operation is synchronous. The Mipd10 HttpConnection establishment and POST request and response are synchronous, blocking as long as connection establishment is underway and waiting on the response.
|
| Recv Operation |
| Description | Receive a message from a HttpDestination. The synchronous response from a send() operation is retrieved. The HttpDestination must match the previous send() operation's HttpDestination in order to return a valid response.
|
| Transformation | The receive operation delivers a Hashtable of String key-value pairs to the caller. The HTTP POST response is assumed to be UTF-8 encoded plain text, where each line pair represents a key-value pair.
|
| Concurrency | Only a single send/recv operation pair can be performed concurrently.
Concurrent operations are not allowed regardless of the Destination. |
| Synchronization | The operation is asynchronous. The receive operation is simply picking up a response which has already been read as part of the send operation, so it is non blocking.
|
