Class Queue

java.lang.Object
gnu.cajo.utils.extra.Queue
All Implemented Interfaces:
Invoke, Serializable, Remote

public class Queue extends Object implements Invoke
This class is a cajo-based implementation of the message communication paradigm. One or more producer objects can invoke methods on this object, and the invocations will be asynchronously performed on one (point to point), or more (publish/subscribe), consumer objects. A producer, by virtue of having its method invocation return immediately and successfully, can be certain its invocation has been enqueued, and will be invoked on the member consumers (if any). The consumers can be either local or remote objects.

A producer enqueues its invocations for the member consumers, by invoking the corresponding method on its reference to an instance of this object. Its argument(s), if any, will be invoked on the matching method of each of the consumer objects, in a separate thread. This creates a dynamic buffer of invocations.

Due to the asynchronous disconnection between the producer and consumer(s), no results can be returned from the method invocations. If a producer wishes to receive data from each of the consumers, it could provide a callback reference as one of the arguments, for example.

Interactions between producers and consumers can be as simple as a single method taking no arguments - notification, to a method taking a single argument - messaging, to multiple methods taking multiple arguments - remote procedure calls.

Finally, this class is serialisable, to allow passing of Queue objects between machines, and replication of Queue objects, the possibilities this creates require a bit of thought indeed...

Version:
1.0, 25-Jun-06
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected LinkedList
    The list of consumers, remote and local, to receive producer invocations.
    protected LinkedList
    The list of all pending producer method invocations.
    private static final long
     
    protected Thread
    This is the thread performing the asynchronous invocation operation, invoking the corresponding method on consumer objects.
    protected final Object
    Some manner of commonly agreed upon descriptor for the subject matter about which the producers and consumers are interested.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Queue(Object topic)
    The constructor simply assigns the topic for the object and returns, as the object is entirely event driven.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dequeue(Object consumer)
    This method is used to remove a consumer from the list.
    void
    enqueue(Object consumer)
    This method is used to add an object to list of consumers awaiting producer invocation.
    invoke(String method, Object args)
    This is the method a producer, local or remote, would invoke, to be performed in a message-based fashion, asynchronously, on all registered consumers.
    static void
    main(String[] args)
    This method will start up a remotely accessible Queue object, in its own JVM.
    void
    This method is called to suspend method invocation dispatching.
    void
    This method is called to resume method invocation dispatching.
    This method is used to request the topic of the producer/consumer community.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:
    • topic

      protected final Object topic
      Some manner of commonly agreed upon descriptor for the subject matter about which the producers and consumers are interested. It must be serialisable.
    • invocations

      protected LinkedList invocations
      The list of all pending producer method invocations.
    • consumers

      protected LinkedList consumers
      The list of consumers, remote and local, to receive producer invocations.
    • thread

      protected transient Thread thread
      This is the thread performing the asynchronous invocation operation, invoking the corresponding method on consumer objects. It is instantiated dynamically, upon the first producer invocation.
  • Constructor Details

    • Queue

      public Queue(Object topic)
      The constructor simply assigns the topic for the object and returns, as the object is entirely event driven. Note: the descriptor object must be serialisable.
      Parameters:
      topic - A descriptor object, mutually agreed upon by all participants
  • Method Details

    • topic

      public Object topic()
      This method is used to request the topic of the producer/consumer community. Note: the object returned may be unknown to caller, thus resulting in a NoClassDefFoundError, in that case, it is probably not a good idea to join the community as either a producer or consumer.
      Returns:
      The community descriptor
    • enqueue

      public void enqueue(Object consumer)
      This method is used to add an object to list of consumers awaiting producer invocation.
      Parameters:
      consumer - The object wishing to subscribe
    • dequeue

      public void dequeue(Object consumer)
      This method is used to remove a consumer from the list.
      Parameters:
      consumer - The object wishing to unsubscribe
    • pause

      public void pause()
      This method is called to suspend method invocation dispatching. Producer invocations will continue to queue. This method is iddmpotent. It can only be invoked locally.
    • resume

      public void resume()
      This method is called to resume method invocation dispatching. This method is idempotent. It can only be invoked locally.
    • invoke

      public Object invoke(String method, Object args)
      This is the method a producer, local or remote, would invoke, to be performed in a message-based fashion, asynchronously, on all registered consumers. This method returns immediately, implicitly guaranteeing the invocation has been successfully enqueued.

      Note: normally invocation of the methods topic, enque, and deque will not be passed along to consumers, as they are performed on the Queue instance. However, invoking topic with any arguments, and enqueue or dequeue with no arguments, these will be passed on to consumers, as they do not apply to the Queue instance.

      Specified by:
      invoke in interface Invoke
      Parameters:
      method - The public method name on the consumer objects to be invoked
      args - The argument(s) to invoke on the consumer object's method, there can be none, to simply perform notification, there can be a single argument to provide data, or there can be a collection to engage a behaviour, presumably, the subscribed object has a matching public method signature.
      Returns:
      null Since consumer invocation is performed asynchronously, there can be no synchronous return data, a callback object reference can be provided as an argument, if result data is required
      Throws:
      RemoteException - If the invocation failed to enqueue, due to a network related error
    • main

      public static void main(String[] args) throws Exception
      This method will start up a remotely accessible Queue object, in its own JVM. For illustrative purposes, the queue object will be wrapped in a MonitorItem, which outputs to the console. It will bind locally under its topic name, and announce itself over multicast, using the cajo IANA UDP address, on port 1198.
      Parameters:
      args - The first string, if defined, will be the topic string, undefined it will be "void", the second, if defined, will be the TCP port number on which the queue will accept invocations, undefined it will be 1198, it can be zero, to use an anonymous port
      Throws:
      Exception - For startup or machine/network configuration issues