QPID-2402 & QPID-2406: Documented the units for the ttl property of Message. Eliminated use of qpid::sys::Duration from API.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@918575 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 56 insertions, 9 deletions

diff --git a/cpp/include/qpid/messaging/Duration.h b/cpp/include/qpid/messaging/Duration.h
new file mode 100644
index 0000000000..5f95acf04d
--- /dev/null
+++ b/cpp/include/qpid/messaging/Duration.h
@@ -0,0 +1,39 @@
+#ifndef QPID_MESSAGING_DURATION_H
+#define QPID_MESSAGING_DURATION_H
+
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ * 
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+#include "qpid/sys/IntegerTypes.h"
+#include <limits>
+
+namespace qpid {
+namespace messaging {
+
+/**
+ * A duration is a time in milliseconds.
+ */
+typedef uint64_t Duration;
+const Duration INFINITE_DURATION = std::numeric_limits<uint64_t>::max();
+const Duration DURATION_SEC  = 1000;
+
+}} // namespace qpid::messaging
+
+#endif  /*!QPID_MESSAGING_DURATION_H*/
diff --git a/cpp/include/qpid/messaging/Message.h b/cpp/include/qpid/messaging/Message.h
index d1028ff330..30e15d79a3 100644
--- a/cpp/include/qpid/messaging/Message.h
+++ b/cpp/include/qpid/messaging/Message.h
@@ -23,6 +23,7 @@
  */
 
 #include <string>
+#include "qpid/messaging/Duration.h"
 #include "qpid/messaging/Variant.h"
 #include "qpid/client/ClientImportExport.h"
 
@@ -67,8 +68,14 @@ class Message
     QPID_CLIENT_EXTERN void setCorrelationId(const std::string&);
     QPID_CLIENT_EXTERN const std::string& getCorrelationId() const;
 
-    QPID_CLIENT_EXTERN void setTtl(uint64_t ttl);
-    QPID_CLIENT_EXTERN uint64_t getTtl() const;
+    /**
+     * Set the time to live for this message in milliseconds.
+     */
+    QPID_CLIENT_EXTERN void setTtl(Duration ttl);
+    /**
+     *Get the time to live for this message in milliseconds.
+     */
+    QPID_CLIENT_EXTERN Duration getTtl() const;
 
     QPID_CLIENT_EXTERN void setDurable(bool durable);
     QPID_CLIENT_EXTERN bool getDurable() const;
diff --git a/cpp/include/qpid/messaging/Receiver.h b/cpp/include/qpid/messaging/Receiver.h
index 0923178065..bc1f39bfc1 100644
--- a/cpp/include/qpid/messaging/Receiver.h
+++ b/cpp/include/qpid/messaging/Receiver.h
@@ -24,7 +24,7 @@
 #include "qpid/Exception.h"
 #include "qpid/client/ClientImportExport.h"
 #include "qpid/client/Handle.h"
-#include "qpid/sys/Time.h"
+#include "qpid/messaging/Duration.h"
 
 namespace qpid {
 namespace client {
@@ -57,14 +57,14 @@ class Receiver : public qpid::client::Handle<ReceiverImpl>
      * available. Returns false if there is no message to give after
      * waiting for the specified timeout.
      */
-    QPID_CLIENT_EXTERN bool get(Message& message, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN bool get(Message& message, Duration timeout=INFINITE_DURATION);
     /**
      * Retrieves a message from this receivers local queue, or waits
      * for upto the specified timeout for a message to become
      * available. Throws NoMessageAvailable if there is no
      * message to give after waiting for the specified timeout.
      */
-    QPID_CLIENT_EXTERN Message get(qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN Message get(Duration timeout=INFINITE_DURATION);
     /**
      * Retrieves a message for this receivers subscription or waits
      * for upto the specified timeout for one to become
@@ -72,7 +72,7 @@ class Receiver : public qpid::client::Handle<ReceiverImpl>
      * that there is no message for the subscription this receiver is
      * serving before returning false.
      */
-    QPID_CLIENT_EXTERN bool fetch(Message& message, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN bool fetch(Message& message, Duration timeout=INFINITE_DURATION);
     /**
      * Retrieves a message for this receivers subscription or waits
      * for up to the specified timeout for one to become
@@ -80,7 +80,7 @@ class Receiver : public qpid::client::Handle<ReceiverImpl>
      * that there is no message for the subscription this receiver is
      * serving before throwing an exception.
      */
-    QPID_CLIENT_EXTERN Message fetch(qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN Message fetch(Duration timeout=INFINITE_DURATION);
     /**
      * Sets the capacity for the receiver. The capacity determines how
      * many incoming messages can be held in the receiver before being
diff --git a/cpp/include/qpid/messaging/Session.h b/cpp/include/qpid/messaging/Session.h
index 46372cb849..87f69f268a 100644
--- a/cpp/include/qpid/messaging/Session.h
+++ b/cpp/include/qpid/messaging/Session.h
@@ -22,6 +22,7 @@
  *
  */
 #include "qpid/Exception.h"
+#include "qpid/messaging/Duration.h"
 #include "qpid/client/ClientImportExport.h"
 #include "qpid/client/Handle.h"
 #include "qpid/sys/Time.h"
@@ -100,7 +101,7 @@ class Session : public qpid::client::Handle<SessionImpl>
      * which case the passed in receiver reference will be set to the
      * receiver for that message or fals if no message was available.
      */
-    QPID_CLIENT_EXTERN bool nextReceiver(Receiver&, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN bool nextReceiver(Receiver&, Duration timeout=INFINITE_DURATION);
     /**
      * Returns the receiver for the next available message. If there
      * are no available messages at present the call will block for up
@@ -108,7 +109,7 @@ class Session : public qpid::client::Handle<SessionImpl>
      * Receiver::NoMessageAvailable if no message became available in
      * time.
      */
-    QPID_CLIENT_EXTERN Receiver nextReceiver(qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    QPID_CLIENT_EXTERN Receiver nextReceiver(Duration timeout=INFINITE_DURATION);
     
     /**
      * Create a new sender through which messages can be sent to the