The definitive guide to ObjectQ's functionality is the set of man pages, which you can either read online, or download as a zip'ped file of MSWord documents to view or print locally.To see all of the documentation please click here...
The description below is intended to be a high-level overview of the major functionality to enable you to navigate the man pages more easily.
ObjectQ has three major components:
- a vendor independent transport, that provides the same simple interface to any of the supported underlying transports - currently DECmessageQ, MQ Series, Tuxedo and plain ol' TCP/IP;
- a standardized message format that permits a loosely-coupled interface between client and server - such that either side can be upgraded without the need to "flash-cut" all clients and servers;
- a higher level object-oriented interface that takes care of matching up incoming responses to previously issued requests - messages on the server side are handled by an "agent", and on the client side by a "manager".
We can summarize each of the major components in turn, and relate them to the man pages that contain all the gory detail.
First, the transport. It supports:
- message transfer across DECmessageQ, MQ Series, Tuxedo or plain TCP/IP without application rewrite; transport used is run-time selectable.
- simple 4 verb API (register, unregister, send, receive).
- blocking or non-blocking receive's, allowing synchronous or asynchronous operation.
- plain FIFO message receipt, or message selection based on run-time selectable criteria.
- load-balancing across multiple servers, according to a user- specified algorithm.
- location independence of servers - actual location is driven by a data file or an X.500 source.
- public-key encryption, ensuring absolute security.
- multiple input and output queues.
- automatic re-connection on transport failure (DmQ only).
- multiple levels of delivery assurance, from none to guaranteed delivery.
The cpTransport man page describes the transport API itself; the cpTransportManager man page explains how the transport is run-time selectable; the cpResource man page shows how transport criteria (such as timeout values) are transferred to the transport; the cpHandle man page describes the "handle" that is used to identify a particular transport and/or queue; the cpSelector man page gives details about the message selection criteria that can be specified; and the cpSnrData man page explains the format of the data file through which load balancing and location-independence are achieved.
Secondly, the messaging. There are 6 pairs (request and response) of message types:
- get - for retrieving information about an object
- set - for modifying information on an object
- create - to create a new object
- delete - to delete an existing object
- action - to execute a function on an object
- event report - for notification of events (initiated by subscription)
Each of these messages contain data stored as attribute-value pairs; information about the data (its name, type, etc) are stored in a "MIB" (Management Information Base) that is machine readable, and loaded at run time. This is how the loose-coupling of either side is achieved. It also means that the MIB definition is the service interface definition, and that new clients can be written to access the service without the need for negotiation of a new interface, and the associated costs of interoperability testing. The message set is closely modelled after the OSI CMIP standard.
It's somewhat misleading to talk of sending messages, since what ObjectQ actually sends is an "envelope", that can contain one or more individual "messages". This is largely for reasons of efficiency.
The cpEnvelope man page describes the envelope; the cpMessage man page describes the messages that the envelope contains; and the cpAttribute man page describes the attributes that each message contains; the cpFilter man page explains how requests can be applied to a range of objects (rather than to just one) by specifying an (arbitrarily complex) instance filter - it is also used to specify events for which notification is required (typically in a subscription request).
The higher level
And finally, the higher level component. On the server side, incoming requests are handled by an "agent", and are passed to the agent by a "dispatcher" that is aware of agents' capabilities and availability. On the client side, requests are sent, and matching responses received, by a "manager"; once again a dispatcher is responsible for delivering responses to the appropriate manager. Applications pass parameters (such as timeout values) to the manager (who in turn passes them down to the transport, or wherever) via a "manager resource".
The cpAgent man page describes a skeletal agent, which an application will subclass to provide specific functionality; the cpManager man page is similar, but for the client side; the cpGenericManager describes a fully-functioning manager, for simple applications that have no need of esoteric features; the cpDispatch man page explains how the dispatcher works; the cpManagerResource man page describes the parameters that may be passed to the manager; and the cpCallBack man page explains one way in which callbacks to application functions can be achieved.
In addition, the cpIntro man page lists error codes that may be returned by the ObjectQ functions, and the cpInit man page describes the initialization function that must be called before all others.