org.jumpi
Interface Jumpi

All Known Subinterfaces:

Jumpi

All Known Implementing Classes:

JumpiImpl

public interface Jumpi

Jumpi, the universal message passing interface written in Java, is a simple, generic, and extensible low level message passing communications API. A Jumpi client application uses the Jumpi API in org.jumpi to perform message passing regardless of underlying protocols and networks. Jumpi is simple, yet not diluted, as can be seen by the scope of the reference implementation provided in the org.jumpi.impl package.

Jumpi provides a means of addressing using Destination. Messages are sent to and received from Destinations. The syntax of Destinations are implementation dependent.

Jumpi provides a single sending primitive, send(org.jumpi.Destination, java.lang.Object, org.jumpi.Selector, java.util.Hashtable). The client application is given a Handle which allows the application to be notified when an asynchronous sending operation has completed, to inquire the status, and cancel the operation before completion.

Jumpi provides a single receiving primitive, recv(org.jumpi.Destination, org.jumpi.Selector, java.util.Hashtable). The client application is given an Handle which allows the application to be notified when an asynchronous receiving operation has received a message, to inquire the status, and cancel the operation before reception has completed.

Jumpi provides additional synchronization support for groups of Handles through the Selector. Jumpi is a Selector factory, and they can be created via the getSelector(). Polling is not necessary in Jumpi. Whether the sending or receiving operation is synchronous or asynchronous is implementation dependent. The intention is that the operations should be implemented asynchronously so that they do not block the caller under normal conditions. Furthermore all synchronous primitives can always be emulated by using asynchronous primitives with a little extra synchronization.

Messages are represented in Jumpi by the java.lang.Object. Jumpi does not prescribe message formats in application nor on the wire. This is implementation dependent.

The Jumpi API is compatible with MIDP1.0, MIDP2.0, Personal Java, JDK1.1 to JDK1.4. Java platform compatibility is implementation dependent. Jumpi implementations can be extremely lightweight, but the details are implementation dependent. It is intended that there should be no explicit limits on the number of Jumpi instances within a single VM, however this too is implementation dependent.

Jumpi is ultimately 'object-oriented' by encapsulating the lowest common denominator functionality needed to communicate between separate entities. Conceptually, Jumpi draws inspiration from MPI and Unix's file descriptor functionality - where file descriptors are used to encapsulate file, socket, named-pipe, pipe, shared memory and other operations. Jumpi is intended to combat the complexity which programmers face currently due to the plethora of similar but different communication API's. Jumpi brings together various technologies under one hat. The conceptual simplicity of MPI as a message passing paradigm was taken directly into Jumpi. There is a strong resemblence between the Jumpi send and recv operations with the MPI_ISEND and MPI_IRECV operations.

Jumpi does not foresee that all communicating parties be Jumpi client applications. Jumpi can be used in cross platform, cross technology, cross language environments. For example, a Jumpi client application can use standard HTTP to get content from a web server which is not a Jumpi client application. Since data representation 'over the wire' is implementation dependent, there is nothing preventing a C# client application communicating with a Java Jumpi client. The Jumpi reference implementation may be ported to other platforms.

Jumpi does not provide any explicit Connection management. The basic reason being that Connection management can always be managed implicitly by Jumpi for a client application and this is done for simplicity. For example, in order to send a message from one application to another via TCP, it is implicit that a TcpConnection must be established between the communicating parties. How the connection is established, the ports used, which party is client and which server, is implementation dependent. With the exception of the MIDP Generic Connection Framework, specifically for mobile and embedded devices, there is no generic connection framework in standard Java. For example creating a JMS connection is very different from creating a TCP connection. Instead of defining a Generic Connection Framework for J2SE, connections were abstracted away. Jumpi has two management calls, startup() and shutdown() which are used to start and stop the Jumpi instance from working. The reason to these operations is to allow indeterminacies of garbage collection and finalization. After Jumpi.shutdown() has returned, the caller is sure that all Jumpi's unused resources are freed. Further motivation for these methods comes because MIDP does not foresee Object finalization. A typical Jumpi implementation will have started threads, which will never know when to finish unless stopped explicitly, if not through shutdown() then via finalization. Introducing a startup and shutdown function, this brings immediately synchronization problems with the send and receive primitives and other operations. Sending and receiving operations started after shutdown() will fail, as too they should fail if started before startup(). Jumpi does not define what the outcome of new and ongoing send or receive operations in race conditions with startup() and shutdown(). It is perfectly satisfactory for an implementation to not synchronize sending and receiving operations with startup and shutdown for performance reasons. In fact not synchronizing is recommended. The logic being that a Jumpi client application has full control of sending and receiving operations, and can perform startup and shutdown when it deems this 'safe' and appropriate. For instance a Jumpi client application can cancel all pending operations and then shutdown. Whether a Jumpi instance can be started again after shutdown is implementation dependent. This is however not recommended.

Jumpi does not throw Exceptions for failed sending and receiving operations. Error situations are detected through the Handle's associated with the operations. The reason for this is that the operations are asynchronous, so that error situations can occur after the thread of control has returned to the application. It is then not possible to throw an Exception. It is the responsibility of the Jumpi client application to check for error situations and handle them.

Jumpi does not provide a callback mechanism for message reception, like onMessage(). In doing so Jumpi avoids unwanted complexity in threading issues. Any thread in onMessage() would belong to Jumpi but would be executing Jumpi client application code. There is always the possibility of RuntimeExceptions, where the question remains as to how to handle them, and deadlock danger when the thread is used to call Jumpi methods.

Support for specific communication protocols, for example TCP or HTTP, specific communications guarantees, such as message ordering and reliability, are strictly implementation dependent and not prescribed.

Additional information, which is implementation specific, can be provided by a Jumpi client application to the implementation via send and receive properties. This is API's extensibility mechanism. For example credentials can be passed to a send, receive or getDestination operation in order to provide information for the establishment of an secure connection.

Method Summary

Destination	getDestination(java.lang.String url) Return a Destination corresponding to the Url.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Return a Destination corresponding to the Url providing the implementation with implementation specific properties.
Destination	getDestination(java.lang.String controller, java.lang.String url) Return a Destination corresponding to the Url, associated with the named Controller.
Destination	getDestination(java.lang.String controller, java.lang.String url, java.util.Hashtable clientProps) Return a Destination corresponding to the Url, associated with the named Controller, providing the implementation with implementation specific properties.
Selector	getSelector() Get a new, empty Selector.
void	manage(java.util.Hashtable parameters) Manage a Jumpi instance.
Handle	recv(Destination dest) Start a receive operation from a Destination.
Handle	recv(Destination dest, java.util.Hashtable clientProps) Start a receive operation from a Destination.
Handle	recv(Destination dest, Selector sel) Start a receive operation from a Destination.
Handle	recv(Destination dest, Selector sel, java.util.Hashtable clientProps) Start a receive operation from a Destination, providing the implementation with implementation specific information as read-only properties.
Handle	send(Destination dest, java.lang.Object msg) Send a message to a Destination.
Handle	send(Destination dest, java.lang.Object msg, java.util.Hashtable clientProps) Send a message to a Destination.
Handle	send(Destination dest, java.lang.Object msg, Selector sel) Send a message to a Destination.
Handle	send(Destination dest, java.lang.Object msg, Selector sel, java.util.Hashtable clientProps) Send a message to a Destination, providing the implementation with implementation specific properties.
void	shutdown() Shutdown a Jumpi instance.
void	startup() Starts a Jumpi instance.

Method Detail

getDestination

public Destination getDestination(java.lang.String controller,
                                  java.lang.String url,
                                  java.util.Hashtable clientProps)

Return a Destination corresponding to the Url, associated with the named Controller, providing the implementation with implementation specific properties.

The syntax of Destination Urls are implementation dependent. Examples can be :

• tcp://[hostname|*]:[port|*]
• udp://[hostname|*]:[port|*]
• http://[hostname|*]:[port|*]
• mpi://communicator:[process-id|*]
• ucp://[hostname|*]:[port|*]
• smpp://[hostname|*]:[port|*]
• mms://[hostname|*]:[port|*]
• sms://msisdn
• email://address
• jms://destinationname[:selector]

The use of '*' is typical for wildcard destinations. Wildcard Destinations match multiple specific destinations. Support for wildcard Destinations is dependent on the Connector.

The available controllers and their names are implementation dependent. In the absence of multiple controllers, the getDestination(String) can be used.

No properties are defined by Jumpi. All properties and their semantics are implementation dependent. The Jumpi implementation may not modify any client properties. They are considered read-only. Information to be provided back to the Jumpi client application can be given through the Destination.getProperties() method.

Parameters:

controller - name of the Controller.

url - Url representation of the Destination.

clientProps - read-only properties for implementation specific use.

Returns:

the Destination corresponding to the Url, or null if unsupported.

Throws:

java.lang.IllegalArgumentException - if any parameters are null.

getDestination

public Destination getDestination(java.lang.String url,
                                  java.util.Hashtable clientProps)

Return a Destination corresponding to the Url providing the implementation with implementation specific properties.

Parameters:

url - the Url representation of the Destination.

clientProps - read-only properties for implementation specific use.

Returns:

the Destination corresponding to the Url, or null if unsupported.

See Also:

getDestination(String,String,Hashtable)

getDestination

public Destination getDestination(java.lang.String url)

Return a Destination corresponding to the Url.

Parameters:

url - the Url representation of the Destination.

Returns:

the Destination corresponding to the Url, or null if unsupported.

Throws:

java.lang.IllegalArgumentException - if url is null.

See Also:

getDestination(String,String,Hashtable)

getDestination

public Destination getDestination(java.lang.String controller,
                                  java.lang.String url)

Return a Destination corresponding to the Url, associated with the named Controller.

Parameters:

controller - name of the Controller.

url - the Url representation of the Destination.

Returns:

the Destination corresponding to the Url, or null if unsupported.

Throws:

java.lang.IllegalArgumentException - if url is null or controller is null.

See Also:

getDestination(String,String,Hashtable)

send

public Handle send(Destination dest,
                   java.lang.Object msg,
                   Selector sel,
                   java.util.Hashtable clientProps)

Send a message to a Destination, providing the implementation with implementation specific properties. The send operation may be asynchronous, in which case the returned Handle can be used to inquire the current status of the operation. Furthermore the operation can be cancelled and the caller can wait for the operation to complete with Handle.waitWhileBlocking(). Whether the operation is synchronous or asynchronous is implementation dependent. Any erroneous condition is stated in the status of the returned Handle. No Exceptions are thrown since with asynchronous sending, error circumstances can occur after returning, but before send completion.

The getDestination(java.lang.String, java.lang.String, java.util.Hashtable) is the only means to get the Destination objects needed for sending.

The type, syntax and semantics of message are implementation dependent. For example, sending an SMS message may prescribe that the message be a java.lang.String with a maximum length of 180 characters. Sending via some other Destination may require a Serializable object. Jumpi does not dictate that messages should be Serializable or infact any restrictions at all. A Jumpi implementation is responsible for transforming the message Object into a format appropriate for the wire protocol.

Message ordering, reliability, quality of service, and performance guarantees are implementation dependent. Whether concurrent sends are possible is implementation dependent, as well as whether send and receive operations may be performed concurrently.

As a convenience, the Handle which is returned is additionally placed into the Selector provided, regardless of the Handle's status.

Parameters:

dest - the Destination to which the message is sent.

msg - the Message.

sel - the Selector into which the Handle is placed.

clientProps - read-only properties for implementation specific use.

Returns:

an Handle associated with the sending operation.

Throws:

java.lang.IllegalArgumentException - if dest or msg are null.

send

public Handle send(Destination dest,
                   java.lang.Object msg)

Send a message to a Destination.

Parameters:

dest - the Destination to which the message is sent.

msg - the Message.

Returns:

the Handle associated with the sending operation.

Throws:

java.lang.IllegalArgumentException - if dest or msg are null.

See Also:

send(Destination,Object,Selector,Hashtable)

send

public Handle send(Destination dest,
                   java.lang.Object msg,
                   Selector sel)

Send a message to a Destination.

Parameters:

dest - the Destination to which the message is sent.

msg - the Message.

sel - the Selector into which the Handle is placed.

Returns:

the Handle associated with the sending operation.

Throws:

java.lang.IllegalArgumentException - if dest or msg are null.

See Also:

send(Destination,Object,Selector,Hashtable)

send

public Handle send(Destination dest,
                   java.lang.Object msg,
                   java.util.Hashtable clientProps)

Send a message to a Destination.

Parameters:

dest - the Destination to which the message is sent.

msg - the Message.

clientProps - read-only properties for implementation specific use.

Returns:

the Handle associated with the sending operation.

Throws:

java.lang.IllegalArgumentException - if dest or msg are null.

See Also:

send(Destination,Object,Selector,Hashtable)

recv

public Handle recv(Destination dest,
                   Selector sel,
                   java.util.Hashtable clientProps)

Start a receive operation from a Destination, providing the implementation with implementation specific information as read-only properties. A received message is made available to the Jumpi client application through the Handle.getMessage() method.

There is no callback registration method for receiving Messages in Jumpi. A receiving operation is completed as soon as a single message has been received. If a Jumpi client application wishes to continuously receive messages from a Destination, then it must continue to call recv for each message. It may be possible to start multiple concurrent receives on the same Destination. This is implementation dependent.

The sender of a message can be inquired through the Handle.getSender() method. This is useful when the Destination on which a receive is taking place is a wildcard destination. For instance, receiving from udp://myhost:* will match datagrams coming from any port on the host called myhost. Once a datagram is received matching this Destination, the sender can be resolved to be udp://myhost:8888.

The receive operation may be asynchronous, in which case the Handle can be used to inquire the current status of the receive operation. Furthermore the operation can be cancelled and the caller can wait for the operation to complete with Handle.waitWhileBlocking().Whether the operation is synchronous or asynchronous is implementation dependent. Any erroneous condition is stated in the status of the returned Handle. No Exceptions are thrown since with asynchronous receiving, error circumstances can occur after returning, but before reception completion.

The type, syntax and semantics of message are implementation dependent. For example, receiving from an email destination may always return an object of type javax.mail.MimeMessage. A Jumpi implementation is responsible for transforming the message Object from received data.

Whether concurrent receives are possible is implementation dependent, as well as whether send and receive operations may be performed concurrently.

Parameters:

dest - the Destination to receive from.

sel - the Selector into which the Handle is placed.

clientProps - read-only implementation specific properties used by the implementation.

Returns:

the Handle associated with the started receive operation.

Throws:

java.lang.IllegalArgumentException - if dest is null.

recv

public Handle recv(Destination dest,
                   java.util.Hashtable clientProps)

Start a receive operation from a Destination.

Parameters:

dest - the Destination to receive from.

clientProps - read-only implementation specific properties used by the implementation.

Returns:

the Handle associated with the started receive operation.

Throws:

java.lang.IllegalArgumentException - if dest is null.

See Also:

recv(Destination, Selector, Hashtable)

recv

public Handle recv(Destination dest)

Start a receive operation from a Destination.

Parameters:

dest - the Destination to receive from.

Returns:

the Handle associated with the started receive operation.

Throws:

java.lang.IllegalArgumentException - if dest is null.

See Also:

recv(Destination, Selector, Hashtable)

recv

public Handle recv(Destination dest,
                   Selector sel)

Start a receive operation from a Destination.

Parameters:

dest - the Destination to receive from.

sel - the Selector into which the Handle is placed.

Returns:

the Handle associated with the started receive operation.

Throws:

java.lang.IllegalArgumentException - if dest is null.

See Also:

recv(Destination, Selector, Hashtable)

getSelector

public Selector getSelector()

Get a new, empty Selector.

Returns:

a new, empty Selector.

startup

public void startup()
             throws java.lang.Exception

Starts a Jumpi instance. Sending and receiving operations will fail before startup. For performance reasons, implementations may exhibit race conditions with send, recv and getDestination, but not with shutdown.

Throws:

java.lang.Exception - when any problems occur during startup. Thereafter the result of any Jumpi operations on the instance are undefined.

See Also:

shutdown()

shutdown

public void shutdown()
              throws java.lang.Exception

Shutdown a Jumpi instance. Sending and receiving operations will fail after shutdown. The outcome of ongoing sending and receiving operations is undefined and is implementation dependent. Good implementations should fail ongoing send and receive operations if shutdown. Whether startup() can be called after shutdown() is implementation dependent.

Throws:

java.lang.Exception - when any problems occurs during shutdown. Thereafter the result of any Jumpi operations on the instance are undefined.

See Also:

startup()

manage

public void manage(java.util.Hashtable parameters)
            throws java.lang.Exception

Manage a Jumpi instance. The management operations defined are implementation dependent. Management may be possible before startup and after shutdown in addition to the typical management after startup, before shutdown.

Parameters:

parameters - in-out parameters and results container.

Throws:

java.lang.Exception - when any problems occurs during management.