You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by ta...@apache.org on 2009/05/22 01:07:39 UTC
svn commit: r777309 - in /activemq/activemq-cpp/trunk/activemq-cpp/src/main:
activemq/commands/ cms/
Author: tabish
Date: Thu May 21 23:07:15 2009
New Revision: 777309
URL: http://svn.apache.org/viewvc?rev=777309&view=rev
Log:
Fix many doxygen warnings and clean up the code documentation for the next release. Remove the toProviderString method from the CMS Destination interface as its no longer needed.
Modified:
activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQQueue.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempQueue.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempTopic.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTopic.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/BytesMessage.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSException.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSProperties.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Closeable.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Connection.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ConnectionFactory.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/DeliveryMode.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Destination.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ExceptionListener.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MapMessage.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Message.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageConsumer.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageListener.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageProducer.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Queue.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/QueueBrowser.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Session.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Startable.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Stoppable.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/StreamMessage.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryQueue.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryTopic.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TextMessage.h
activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Topic.h
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQQueue.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQQueue.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQQueue.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQQueue.h Thu May 21 23:07:15 2009
@@ -97,16 +97,6 @@
}
/**
- * Converts the Destination to a String value representing the
- * Provider specific name fot this destination, which is not
- * necessarily equal to the User Supplied name of the Destination
- * @return Provider specific Name
- */
- virtual std::string toProviderString() const {
- return this->getPhysicalName();
- }
-
- /**
* Creates a new instance of this destination type that is a
* copy of this one, and returns it.
* @returns cloned copy of this object
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempQueue.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempQueue.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempQueue.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempQueue.h Thu May 21 23:07:15 2009
@@ -94,16 +94,6 @@
}
/**
- * Converts the Destination to a String value representing the
- * Provider specific name fot this destination, which is not
- * necessarily equal to the User Supplied name of the Destination
- * @return Provider specific Name
- */
- virtual std::string toProviderString() const {
- return this->getPhysicalName();
- }
-
- /**
* Creates a new instance of this destination type that is a
* copy of this one, and returns it.
* @returns cloned copy of this object
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempTopic.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempTopic.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempTopic.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTempTopic.h Thu May 21 23:07:15 2009
@@ -93,16 +93,6 @@
}
/**
- * Converts the Destination to a String value representing the
- * Provider specific name fot this destination, which is not
- * necessarily equal to the User Supplied name of the Destination
- * @return Provider specific Name
- */
- virtual std::string toProviderString() const {
- return this->getPhysicalName();
- }
-
- /**
* Creates a new instance of this destination type that is a
* copy of this one, and returns it.
* @returns cloned copy of this object
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTopic.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTopic.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTopic.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/activemq/commands/ActiveMQTopic.h Thu May 21 23:07:15 2009
@@ -99,16 +99,6 @@
}
/**
- * Converts the Destination to a String value representing the
- * Provider specific name fot this destination, which is not
- * necessarily equal to the User Supplied name of the Destination
- * @return Provider specific Name
- */
- virtual std::string toProviderString() const {
- return this->getPhysicalName();
- }
-
- /**
* Creates a new instance of this destination type that is a
* copy of this one, and returns it.
* @returns cloned copy of this object
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/BytesMessage.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/BytesMessage.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/BytesMessage.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/BytesMessage.h Thu May 21 23:07:15 2009
@@ -36,7 +36,7 @@
* typically not used, since the inclusion of properties may affect the format.
*
* The primitive types can be written explicitly using methods for each type. Because the
- * C++ language is more limited when dealing with primtive types the JMS equivalent generic
+ * C++ language is more limited when dealing with primitive types the JMS equivalent generic
* read and write methods that take Java objects cannot be provided in the CMS API.
*
* When the message is first created, and when clearBody is called, the body of the message
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSException.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSException.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSException.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSException.h Thu May 21 23:07:15 2009
@@ -28,21 +28,30 @@
namespace cms{
- class CMSExceptionData;
+ class CMSExceptionData;
/**
- * This class represents an error that has occurred in cms, providers
+ * CMS API Exception that is the base for all exceptions thrown from CMS
+ * classes.
+ * <p>
+ * This class represents an error that has occurred in CMS, providers
* can wrap provider specific exceptions in this class by setting the
* cause to an instance of a provider specific exception provided it
* can be cast to an std::exception.
+ * <p>
+ * Since the contained cause exception is of type std::exception and the
+ * C++ exception class has no clone or copy method defined the contained
+ * exception can only be owned by one instance of an CMSException. To that
+ * end the class hands off the exception to each successive copy so care must
+ * be taken when handling CMSException instances.
*
* @since 1.0
*/
class CMS_API CMSException : public std::exception {
private:
- // The actual data that defines this exception.
- CMSExceptionData* data;
+ // The actual data that defines this exception.
+ CMSExceptionData* data;
public:
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSProperties.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSProperties.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSProperties.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/CMSProperties.h Thu May 21 23:07:15 2009
@@ -99,7 +99,7 @@
/**
* Method that serializes the contents of the property map to
- * an arryay.
+ * an array.
*
* @return list of pairs where the first is the name and the second
* is the value.
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Closeable.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Closeable.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Closeable.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Closeable.h Thu May 21 23:07:15 2009
@@ -26,6 +26,10 @@
/**
* Interface for a class that implements the close method.
*
+ * A class that implements this interface should release all resources upon the close
+ * call and should throw an exception from any methods that require those resources
+ * after they have been closed.
+ *
* @since 1.0
*/
class CMS_API Closeable{
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Connection.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Connection.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Connection.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Connection.h Thu May 21 23:07:15 2009
@@ -31,9 +31,9 @@
/**
* The client's connection to its provider.
- *
+ * <p>
* Connections support concurrent use.
- *
+ * <p>
* A connection serves several purposes:
* - It encapsulates an open connection with a JMS provider. It typically represents
* an open TCP/IP socket between a client and the service provider software.
@@ -47,21 +47,21 @@
* with a single connection. Other more advanced applications may use several connections.
* The CMS API does not architect a reason for using multiple connections; however, there
* may be operational reasons for doing so.
- *
+ * <p>
* A CMS client typically creates a connection, one or more sessions, and a number of message
* producers and consumers. When a connection is created, it is in stopped mode. That means
* that no messages are being delivered.
- *
+ * <p>
* It is typical to leave the connection in stopped mode until setup is complete (that is,
* until all message consumers have been created). At that point, the client calls the
* connection's start method, and messages begin arriving at the connection's consumers.
* This setup convention minimizes any client confusion that may result from asynchronous
* message delivery while the client is still in the process of setting itself up.
- *
+ * <p>
* A connection can be started immediately, and the setup can be done afterwards. Clients
* that do this must be prepared to handle asynchronous message delivery while they are still
* in the process of setting up.
- *
+ * <p>
* A message producer can send messages while a connection is stopped.
*
* @since 1.0
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ConnectionFactory.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ConnectionFactory.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ConnectionFactory.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ConnectionFactory.h Thu May 21 23:07:15 2009
@@ -46,8 +46,10 @@
* delivered until the Connection.start method is explicitly
* called.
*
- * @return Pointer to a connection object, caller owns the pointer
- * @throws CMSException
+ * @return A pointer to a connection object, caller owns the pointer and
+ * is responsible for closing the connection and deleting the instance.
+ *
+ * @throws CMSException if an internal error occurs while creating the Connection.
*/
virtual Connection* createConnection() throw ( CMSException ) = 0;
@@ -61,11 +63,13 @@
* were set in the Constructor.
*
* @param username
- * to authenticate with
+ * The user name used to authenticate with the Provider.
* @param password
- * to authenticate with
- * @returns a Connection Pointer
- * @throws CMSException
+ * The password used to authenticate with the Provider.
+ *
+ * @return A pointer to a connection object, caller owns the pointer and
+ * is responsible for closing the connection and deleting the instance.
+ * @throws CMSException if an internal error occurs while creating the Connection.
*/
virtual cms::Connection* createConnection( const std::string& username,
const std::string& password )
@@ -81,14 +85,16 @@
* were set in the Constructor.
*
* @param username
- * to authenticate with
+ * The user name used to authenticate with the Provider.
* @param password
- * to authenticate with
+ * The password used to authenticate with the Provider.
* @param clientId
- * to assign to connection if "" then a random client Id is
- * created for this connection.
- * @returns a Connection Pointer
- * @throws CMSException
+ * The Client Id assigned to connection. If the id is the empty string ("")
+ * then a random client Id is created for this connection.
+ *
+ * @return A pointer to a connection object, caller owns the pointer and
+ * is responsible for closing the connection and deleting the instance.
+ * @throws CMSException if an internal error occurs while creating the Connection.
*/
virtual cms::Connection* createConnection( const std::string& username,
const std::string& password,
@@ -104,10 +110,13 @@
* use this method to remain abstracted from the specific CMS implementation
* being used.
*
- * @param brokerURI - the address to use to connect to the broker.
+ * @param brokerURI
+ * The remote address to use to connect to the Provider.
+ *
+ * @return A pointer to a provider specific implementation of the ConnectionFactory
+ * interface, the caller is responsible for deleting this resource.
*
- * @returns Provider specific ConnectionFactory
- * @throws CMSException if and error occurs.
+ * @throws CMSException if an internal error occurs while creating the ConnectionFactory.
*/
static ConnectionFactory* createCMSConnectionFactory( const std::string& brokerURI )
throw ( cms::CMSException );
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/DeliveryMode.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/DeliveryMode.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/DeliveryMode.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/DeliveryMode.h Thu May 21 23:07:15 2009
@@ -25,6 +25,21 @@
/**
* This is an Abstract class whose purpose is to provide a container
* for the delivery mode enumeration for CMS messages.
+ * <p>
+ * When a client sends a <code>cms::Message</code> it can mark the Message as either
+ * Persistent or Non-Persistent. If the client feels that the Message cannot be lost in
+ * transit it should mark it as Persistent, otherwise if it is allowable for a Message to
+ * occasionally be lost it can mark it as Non-Persistent. This allows the Provider to
+ * balance make tradeoffs between balance and Message throughput.
+ * <p>
+ * The DeliveryMode covers only the transport of the Message for sending client to its
+ * destination and doesn't apply to the receiving Message consumer. The receiving
+ * Consumer can drop Message's based on configuration such as memory limits or Message
+ * filtering.
+ * <p>
+ * A message is guaranteed to be delivered once and only once by a CMS provider if the
+ * delivery mode of the message is PERSISTENT and the configuration of the Message
+ * consumer allows for it.
*
* @since 1.0
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Destination.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Destination.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Destination.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Destination.h Thu May 21 23:07:15 2009
@@ -27,7 +27,11 @@
/**
* A Destination object encapsulates a provider-specific address.
- *
+ * <p>
+ * There is no standard definition of a Destination address, each provider can
+ * provide its own definition and there can be configuration data attached to the
+ * Destination address.
+ * <p>
* All CMS Destination objects support concurrent use.
*
* @since 1.0
@@ -54,17 +58,6 @@
virtual DestinationType getDestinationType() const = 0;
/**
- * Converts the Destination to a String value representing the
- * Provider specific name for this destination. This name must
- * uniquely identify a particular destination. For example, a topic
- * and a queue both named "FOO" must not have equivalent provider
- * strings.
- *
- * @return Provider specific Name
- */
- virtual std::string toProviderString() const = 0;
-
- /**
* Creates a new instance of this destination type that is a
* copy of this one, and returns it.
*
@@ -73,7 +66,7 @@
virtual cms::Destination* clone() const = 0;
/**
- * Copies the contents of the given Destinastion object to this one.
+ * Copies the contents of the given Destination object to this one.
*
* @param source
* The source Destination object.
@@ -85,7 +78,7 @@
* that was specified. This is a deviation from the JMS spec
* but necessary due to C++ restrictions.
*
- * @return const reference to a properties object.
+ * @return A {const} reference to a CMSProperties object.
*/
virtual const CMSProperties& getCMSProperties() const = 0;
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ExceptionListener.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ExceptionListener.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ExceptionListener.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/ExceptionListener.h Thu May 21 23:07:15 2009
@@ -27,10 +27,10 @@
* If a CMS provider detects a serious problem, it notifies the client
* application through an <code>ExceptionListener</code> that is registered
* with the <code>Connection</code>.
- *
+ * <p>
* An exception listener allows a client to be notified of a problem asynchronously.
- * Some connections only consume messages, so they would have no other way to learn
- * that their connection has failed.
+ * Some connections only consume messages via the asynchronous event mechanism so
+ * they would have no other way to learn that their connection has failed.
*
* @since 1.0
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MapMessage.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MapMessage.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MapMessage.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MapMessage.h Thu May 21 23:07:15 2009
@@ -46,6 +46,7 @@
*
* A value written as the row type can be read as the column type.
*
+ * <PRE>
* | | boolean byte short char int long float double String byte[]
* |----------------------------------------------------------------------
* |boolean | X X
@@ -59,6 +60,7 @@
* |String | X X X X X X X X
* |byte[] | X
* |----------------------------------------------------------------------
+ * </PRE>
*
* @since 1.0
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Message.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Message.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Message.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Message.h Thu May 21 23:07:15 2009
@@ -29,6 +29,27 @@
* Root of all messages. As in JMS, a message is comprised of 3 parts:
* CMS-specific headers, user-defined properties, and the body.
*
+ * <B>Message Bodies</B>
+ *
+ * The CMS API defines four types of message bodies, each type is contained within its
+ * own Message Interface definition.
+ *
+ * - Stream - A StreamMessage object's message body contains a stream of primitive values
+ * in the C++ language. It is filled and read sequentially. Unlike the
+ * BytesMessage type the values written to a StreamMessage retain information
+ * on their type and rules for type conversion are enforced when reading back
+ * the values from the Message Body.
+ * - Map - A MapMessage object's message body contains a set of name-value pairs, where
+ * names are std::string objects, and values are C++ primitives. The entries can
+ * be accessed sequentially or randomly by name. The MapMessage makes no garuntee
+ * on the order of the elements within the Message body.
+ * - Text - A TextMessage object's message body contains a std::string object. This message
+ * type can be used to transport plain-text messages, and XML messages.
+ * - Bytes - A BytesMessage object's message body contains a stream of uninterpreted bytes.
+ * This message type is for literally encoding a body to match an existing message
+ * format. In many cases, it is possible to use one of the other body types,
+ * which are easier to use.
+ *
* <B>Message Properties</B>
*
* Message properties support the following conversion table. The marked cases
@@ -39,6 +60,7 @@
*
* A value written as the row type can be read as the column type.
*
+ * <PRE>
* | | boolean byte short int long float double String
* |----------------------------------------------------------
* |boolean | X X
@@ -50,6 +72,7 @@
* |double | X X
* |String | X X X X X X X X
* |----------------------------------------------------------
+ * </PRE>
*
* When a Message is delivered its properties are considered to be in a read-only
* mode and cannot be changed. Attempting to change the value of a delivered
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageConsumer.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageConsumer.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageConsumer.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageConsumer.h Thu May 21 23:07:15 2009
@@ -27,21 +27,21 @@
/**
* A client uses a <code>MessageConsumer</code> to received messages
- * from a destination.<br>
- * <br>
+ * from a destination.
+ *
* A client may either synchronously receive a message consumer's messages
- * or have the consumer asynchronously deliver them as they arrive. <br>
- * <br>
+ * or have the consumer asynchronously deliver them as they arrive.
+ *
* For synchronous receipt, a client can request the next message from a
* message consumer using one of its <code>receive</code> methods. There are
* several variations of <code>receive</code> that allow a client to poll or
- * wait for the next message.<br>
- * <br>
+ * wait for the next message.
+ *
* For asynchronous delivery, a client can register a
* <code>MessageListener</code> object with a message consumer. As messages
* arrive at the message consumer, it delivers them by calling the
* <code>MessageListener</code>'s <code>onMessage</code> method.
- * <br>
+ *
* When the MessageConsumer's close method is called the method can block while
* an asynchronous message delivery is in progress or until a <code>receive</code>
* operation completes. A blocked consumer in a <code>receive</code> call will
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageListener.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageListener.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageListener.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageListener.h Thu May 21 23:07:15 2009
@@ -40,7 +40,7 @@
* reference can be to any of the Message types. a dynamic cast is used
* to find out what type of message this is. The lifetime of this
* object is only guaranteed to be for life of the onMessage function
- * after this callback returns the message may no longer exists. Users should
+ * after this call-back returns the message may no longer exists. Users should
* copy the data or clone the message if they wish to retain information that
* was contained in this Message.
*
@@ -48,7 +48,7 @@
* exception.
*
* @param message
- * Message object const pointer recipient does not own.
+ * Message object {const} pointer recipient does not own.
*/
virtual void onMessage( const Message* message ) = 0;
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageProducer.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageProducer.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageProducer.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/MessageProducer.h Thu May 21 23:07:15 2009
@@ -29,20 +29,20 @@
/**
* A client uses a <code>MessageProducer</code> object to send messages to
- * a destination. A <code>MessageProducer</code> object is created by
+ * a Destination. A <code>MessageProducer</code> object is created by
* passing a <code>Destination</code> object to a message-producer creation
- * method supplied by a session.<br>
- * <br>
+ * method supplied by a session.
+ *
* A client also has the option of creating a message producer without
- * supplying a destination. In this case, a destination must be provided
+ * supplying a destination. In this case, a Destination must be provided
* with every send operation. A typical use for this kind of message
* producer is to send replies to requests using the request's CMSReplyTo
- * destination.<br>
- * <br>
+ * destination.
+ *
* A client can specify a default delivery mode, priority, and time to live
* for messages sent by a message producer. It can also specify the
* delivery mode, priority, and time to live for an individual message.<br>
- * <br>
+ *
* A client can specify a time-to-live value in milliseconds for each
* message it sends. This value defines a message expiration time that is
* the sum of the message's time-to-live and the GMT when it is sent (for
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Queue.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Queue.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Queue.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Queue.h Thu May 21 23:07:15 2009
@@ -27,6 +27,11 @@
/**
* An interface encapsulating a provider-specific queue name.
*
+ * Messages sent to a Queue are sent to a Single Subscriber on that Queue Destination.
+ * This allows for Queues to be used as load balances implementing a SEDA based architecture.
+ * The length of time that a Provider will store a Message in a Queue is not defined by
+ * the CMS API, consult your Provider documentation for this information.
+ *
* @since 1.0
*/
class CMS_API Queue : public Destination{
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/QueueBrowser.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/QueueBrowser.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/QueueBrowser.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/QueueBrowser.h Thu May 21 23:07:15 2009
@@ -31,6 +31,11 @@
/**
* This class implements in interface for browsing the messages in a Queue
* without removing them.
+ * <p>
+ * The <code>getEnumeration</code> method of this class returns a static snapshot of
+ * the Queue at the time the method is called. Since new Message's can be arriving and
+ * old Message's could expire the client should periodically refresh its view by calling
+ * <code>getEnumeration</code> again.
*
* @since 1.1
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Session.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Session.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Session.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Session.h Thu May 21 23:07:15 2009
@@ -76,6 +76,22 @@
* - Invoking any other Session method on a closed session must throw an
* IllegalStateException. Closing a closed session must not throw any exceptions.
*
+ * <B>Transacted Sessions</B>
+ *
+ * When a Session is created it can be set to operate in a Transaction based mode. Each
+ * Session then operates in a single transaction for all Producers and Consumers of that
+ * Session. Messages sent and received within a Transaction are grouped into an atomic
+ * unit that is committed or rolled back together.
+ *
+ * For a MessageProducer this implies that all messages sent by the producer are not sent
+ * to the Provider unit the commit call is made. Rolling back the Transaction results in
+ * all produced Messages being dropped.
+ *
+ * For a MessageConsumer this implies that all received messages are not Acknowledged until
+ * the Commit call is made. Rolling back the Transaction results in all Consumed Message
+ * being redelivered to the client, the Provider may allow configuration that limits the
+ * Maximum number of redeliveries for a Message.
+ *
* @since 1.0
*/
class CMS_API Session : public Closeable {
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Startable.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Startable.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Startable.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Startable.h Thu May 21 23:07:15 2009
@@ -26,6 +26,11 @@
/**
* Interface for a class that implements the start method.
*
+ * An object that implements the Startable interface implies that until its start
+ * method is called it will be considered to be in a closed or stopped state and will
+ * throw an Exception to indicate that it is not in an started state if one of its
+ * methods is called.
+ *
* @since 1.0
*/
class CMS_API Startable {
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Stoppable.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Stoppable.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Stoppable.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Stoppable.h Thu May 21 23:07:15 2009
@@ -26,6 +26,11 @@
/**
* Interface for a class that implements the stop method.
*
+ * An object that implements this interface implies that it will halt all operations
+ * that result in events being propagated to external users, internally the Object
+ * can continue to process data but not events will be generated to clients and methods
+ * that return data will not return valid results until the object is started again.
+ *
* @since 1.0
*/
class CMS_API Stoppable{
@@ -36,7 +41,7 @@
/**
* Stops this service.
*
- * @throws CMSException - if an internal error occurs whle stopping the Service.
+ * @throws CMSException - if an internal error occurs while stopping the Service.
*/
virtual void stop() throw( CMSException ) = 0;
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/StreamMessage.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/StreamMessage.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/StreamMessage.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/StreamMessage.h Thu May 21 23:07:15 2009
@@ -40,6 +40,7 @@
*
* A value written as the row type can be read as the column type.
*
+ * <PRE>
* | | boolean byte short char int long float double String byte[]
* |----------------------------------------------------------------------
* |boolean | X X
@@ -53,7 +54,7 @@
* |String | X X X X X X X X
* |byte[] | X
* |----------------------------------------------------------------------
- *
+ * </PRE>
*
* @since 1.3
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryQueue.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryQueue.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryQueue.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryQueue.h Thu May 21 23:07:15 2009
@@ -25,7 +25,14 @@
namespace cms{
/**
- * An interface encapsulating a provider-specific queue name.
+ * Defines a Temporary Queue based Destination.
+ *
+ * A TemporaryQueue is a special type of Queue Destination that can only be consumed
+ * from the Connection which created it. TemporaryQueues are most commonly used as the
+ * reply to address for Message's that implement the request response pattern.
+ *
+ * A TemporaryQueue is guaranteed to exist at the Provider only for the lifetime of the
+ * Connection that created it.
*
* @since 1.0
*/
@@ -44,7 +51,7 @@
virtual std::string getQueueName() const throw( CMSException ) = 0;
/**
- * Destroy's the Temp Destination at the Broker
+ * Destroy's the Temporary Destination at the Provider.
*
* @throws CMSException - if an internal error occurs.
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryTopic.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryTopic.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryTopic.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TemporaryTopic.h Thu May 21 23:07:15 2009
@@ -25,10 +25,18 @@
namespace cms{
/**
- * An interface encapsulating a provider-specific topic name.
+ * Defines a Temporary Topic based Destination.
+ *
+ * A TemporaryTopic is a special type of Topic Destination that can only be consumed
+ * from the Connection which created it. TemporaryTopics are most commonly used as the
+ * reply to address for Message's that implement the request response pattern.
+ *
+ * A TemporaryTopic is guaranteed to exist at the Provider only for the lifetime of the
+ * Connection that created it.
+ *
+ * @since 1.0
*/
- class CMS_API TemporaryTopic : public Destination
- {
+ class CMS_API TemporaryTopic : public Destination {
public:
virtual ~TemporaryTopic() {}
@@ -43,7 +51,7 @@
virtual std::string getTopicName() const throw( CMSException ) = 0;
/**
- * Destroy's the Temp Destination at the Broker
+ * Destroy's the Temporary Destination at the Provider
*
* @throws CMSException
*/
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TextMessage.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TextMessage.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TextMessage.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/TextMessage.h Thu May 21 23:07:15 2009
@@ -27,6 +27,14 @@
/**
* Interface for a text message.
*
+ * A TextMessage can contain any Text based pay load such as an XML Document or
+ * other Text based document.
+ *
+ * Like all Messages, a TextMessage is received in Read-Only mode, any attempt to write
+ * to the Message will result in a MessageNotWritableException being thrown until the
+ * <code>clearBody</code> method is called which will erase the contents and place the
+ * message back in a read / write mode.
+ *
* @since 1.0
*/
class CMS_API TextMessage : public Message{
Modified: activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Topic.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Topic.h?rev=777309&r1=777308&r2=777309&view=diff
==============================================================================
--- activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Topic.h (original)
+++ activemq/activemq-cpp/trunk/activemq-cpp/src/main/cms/Topic.h Thu May 21 23:07:15 2009
@@ -27,6 +27,10 @@
/**
* An interface encapsulating a provider-specific topic name.
*
+ * A Topic is a Publish / Subscribe type Destination. All Messages sent to a Topic are
+ * broadcast to all Subscribers of that Topic unless the Subscriber defines a Message
+ * selector that filters out that Message.
+ *
* @since 1.0
*/
class CMS_API Topic : public Destination{