activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tab...@apache.org
Subject svn commit: r777309 - in /activemq/activemq-cpp/trunk/activemq-cpp/src/main: activemq/commands/ cms/
Date Thu, 21 May 2009 23:07:39 GMT
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{



Mime
View raw message