Merge pull request #241 from eclipse-uprotocol/v1.0_up-v1.6.0

include/up-cpp/communication/NotificationSink.h

@@ -41,20 +41,44 @@ struct NotificationSink {
 	/// Resetting the unique_ptr for the NotificationSink will automatically
 	/// unregister the callback.
 	///
-	/// @param sink URI of this uE. The authority and entity will be replaced
-	///             automatically with those found in the transport's default.
-	/// @param callback Called when a notification is received.
-	/// @param source_filter (Optional) URI to compare against notification
-	///                      sources. Only notifications that match will be
-	///                      forwarded tot he callback.
+	/// @param transport Shared pointer to a transport instance.
+	/// @param callback Called when a notification is received from the source.
+	/// @param source_filter Notifications matching this source pattern will
+	///                      be passed to the callback.
+	///
+	/// @remarks The transport's entity URI will be used as a sink filter when
+	///          the callback is registered with the transport.
+	///
+	/// @throws datamodel::validator::uri::InvalidUUri if the source_filter
+	///         is an invalid pattern for matching notification messages.
+	/// @throws transport::NullTransport if the transport pointer is nullptr.
 	///
 	/// @returns
 	///    * unique_ptr to a NotificationSink if the callback was connected
 	///      successfully.
 	///    * UStatus containing an error state otherwise.
-	static SinkOrStatus create(std::shared_ptr<transport::UTransport> transport,
-	                           const v1::UUri& sink, ListenCallback&& callback,
-	                           std::optional<v1::UUri>&& source_filter);
+	[[nodiscard]] static SinkOrStatus create(
+	    std::shared_ptr<transport::UTransport> transport,
+	    ListenCallback&& callback, const v1::UUri& source_filter);
+
+	/// @note DEPRECATED
+	/// @brief Create a notification sink to receive notifications.
+	///
+	/// Now a wrapper for create(transport, callback, source_filter)
+	///
+	/// @param sink URI of this uE. Must be transport->getEntityUri().
+	/// @param callback Called when a notification is received.
+	/// @param source_filter Notifications matching this pattern will be
+	///                      forwarded to the callback. MUST HAVE A VALUE.
+	///
+	/// @throws InvalidUUri if sink is not transport->getEntityUri().
+	/// @throws InvalidUUri if source_filter has no value.
+	[[deprecated(
+	    "See alternate overload of "
+	    "create()")]] [[nodiscard]] static SinkOrStatus
+	create(std::shared_ptr<transport::UTransport> transport,
+	       const v1::UUri& sink, ListenCallback&& callback,
+	       std::optional<v1::UUri>&& source_filter);
 
 	~NotificationSink() = default;
 

include/up-cpp/datamodel/builder/UMessage.h

@@ -234,7 +234,10 @@ struct UMessageBuilder {
 
 	/// @brief Access the attributes of the message being built.
 	/// @return A reference to the attributes of the message being built.
-	[[nodiscard]] const v1::UAttributes& attributes() const {
+	[[deprecated(
+	    "Created for tests. Unused now. Do not use")]] [[nodiscard]] const v1::
+	    UAttributes&
+	    attributes() const {
 		return attributes_;
 	}
 

include/up-cpp/datamodel/validator/UUri.h

@@ -30,7 +30,15 @@ enum class Reason {
 	///        for this particular form.
 	DISALLOWED_WILDCARD,
 	/// @brief The resource ID is not in the allowed range for this URI form.
-	BAD_RESOURCE_ID
+	BAD_RESOURCE_ID,
+	/// @brief The URI has a blank (local) authority name
+	LOCAL_AUTHORITY,
+	/// @brief uE Major Version is greater than uint8_t max
+	VERSION_OVERFLOW,
+	/// @brief Resource ID is greater than uint16_t max
+	RESOURCE_OVERFLOW,
+	/// @brief Authority Name is longer than 128 characters
+	AUTHORITY_TOO_LONG
 };
 
 /// @brief Get a descriptive message for a reason code.
@@ -49,7 +57,13 @@ std::string_view message(Reason);
 ///     }
 using ValidationResult = std::tuple<bool, std::optional<Reason>>;
 
-/// @brief Checks if UUri is a valid UUri of any format.
+/// @note DEPRECATED - This check can produce misleading results. It doesn't
+///       handle filters with wildcards. It also is not very useful when
+///       checking URI fields in messages where a message type is already
+///       available. In those cases, the appropriate type-specfic check should
+///       be used instead.
+///
+/// @brief Checks if UUri is a valid UUri for use as an attribute in a message
 ///
 /// A UUri is valid if:
 ///
@@ -59,7 +73,14 @@ using ValidationResult = std::tuple<bool, std::optional<Reason>>;
 ///     * isValidRpcResponse()
 ///     * isValidPublishTopic()
 ///     * isValidNotification()
-[[nodiscard]] ValidationResult isValid(const v1::UUri&);
+[[deprecated(
+    "Use isValidFilter or a message-type-specific "
+    "validator")]] [[nodiscard]] ValidationResult
+isValid(const v1::UUri&);
+
+/// @brief Checks if a UUri is valid as a source_filter or sink_filter when
+///        registering a listener with a transport.
+[[nodiscard]] ValidationResult isValidFilter(const v1::UUri&);
 
 /// @brief Checks if UUri is valid for invoking an RPC method
 ///
@@ -73,12 +94,18 @@ using ValidationResult = std::tuple<bool, std::optional<Reason>>;
 /// resource_id must be 0.
 [[nodiscard]] ValidationResult isValidRpcResponse(const v1::UUri&);
 
-/// @brief Checks if UUri is valid as a default source on a UTransport.
+/// @brief Checks if UUri is valid as an entity URI for a UTransport.
 ///
-/// @note This just calls isValidRpcResponse() because the requirements are the
-///       same in both cases. It is provided as a separate function here for
-///       improved readability where it is called.
-[[nodiscard]] ValidationResult isValidDefaultSource(const v1::UUri&);
+/// @note The requirements for this URI are identical to isValidRpcResponse()
+///       except that the authority name is not allowed to be blank.
+[[nodiscard]] ValidationResult isValidDefaultEntity(const v1::UUri&);
+
+/// @note DEPRECATED
+/// @see isValidDefaultEntity()
+/// @brief Checks if UUri is valid as a default source on a UTransport.
+[[deprecated(
+    "Use isValidDefaultEntity instead")]] [[nodiscard]] ValidationResult
+isValidDefaultSource(const v1::UUri&);
 
 /// @brief Checks if UUri is valid for publishing to a topic, OR as a source
 ///        and sink for sending notifications, OR as a sink for receiving
@@ -134,8 +161,10 @@ using ValidationResult = std::tuple<bool, std::optional<Reason>>;
 /// @remarks Generally used by L2 client interfaces. Not used by checks that
 ///          return ValidationResult.
 struct InvalidUUri : public std::invalid_argument {
-	// Inherit constructors
-	using std::invalid_argument::invalid_argument;
+	// Forward constructors
+	template <typename... Args>
+	InvalidUUri(Args&&... args)
+	    : std::invalid_argument(std::forward<Args>(args)...) {}
 
 	InvalidUUri(InvalidUUri&&) noexcept;
 	InvalidUUri& operator=(InvalidUUri&&) noexcept;