Struct UMessageBuilder

Source

pub struct UMessageBuilder { /* private fields */ }

Expand description

A builder for creating UMessages.

Messages are being used by a uEntity to inform other entities about the occurrence of events and/or to invoke service operations provided by other entities.

Implementations§

Source §

impl UMessageBuilder

Source

pub fn publish(topic: UUri) -> UMessageBuilder

Gets a builder for creating publish messages.

A publish message is used to notify all interested consumers of an event that has occurred. Consumers usually indicate their interest by subscribing to a particular topic.

§Arguments

topic - The topic to publish the message to.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let topic = UUri::try_from("//my-vehicle/4210/1/B24D")?;
let message = UMessageBuilder::publish(topic.clone())
                   .build_with_payload("closed", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.type_unchecked(), UMessageType::UMESSAGE_TYPE_PUBLISH);
assert_eq!(message.priority_unchecked(), UPriority::UPRIORITY_CS1);
assert_eq!(message.source_unchecked(), &topic);

Source

pub fn notification(origin: UUri, destination: UUri) -> UMessageBuilder

Gets a builder for creating notification messages.

A notification is used to inform a specific consumer about an event that has occurred.

§Arguments

origin - The component that the notification originates from.
destination - The URI identifying the destination to send the notification to.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let origin = UUri::try_from("//my-vehicle/4210/5/F20B")?;
let destination = UUri::try_from("//my-cloud/CCDD/2/0")?;
let message = UMessageBuilder::notification(origin.clone(), destination.clone())
                   .build_with_payload("unexpected movement", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.type_unchecked(), UMessageType::UMESSAGE_TYPE_NOTIFICATION);
assert_eq!(message.priority_unchecked(), UPriority::UPRIORITY_CS1);
assert_eq!(message.source_unchecked(), &origin);
assert_eq!(message.sink_unchecked(), &destination);

Source

pub fn request( method_to_invoke: UUri, reply_to_address: UUri, ttl: u32, ) -> UMessageBuilder

Gets a builder for creating RPC request messages.

A request message is used to invoke a service’s method with some input data, expecting the service to reply with a response message which is correlated by means of the request_id.

The builder will be initialized with UPriority::UPRIORITY_CS4.

§Arguments

method_to_invoke - The URI identifying the method to invoke.
reply_to_address - The URI that the sender of the request expects the response message at.
ttl - The number of milliseconds after which the request should no longer be processed by the target service. The value is capped at i32::MAX.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let method_to_invoke = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let message = UMessageBuilder::request(method_to_invoke.clone(), reply_to_address.clone(), 5000)
                   .build_with_payload("lock", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.type_unchecked(), UMessageType::UMESSAGE_TYPE_REQUEST);
assert_eq!(message.priority_unchecked(), UPriority::UPRIORITY_CS4);
assert_eq!(message.source_unchecked(), &reply_to_address);
assert_eq!(message.sink_unchecked(), &method_to_invoke);
assert_eq!(message.ttl_unchecked(), 5000);

Source

pub fn response( reply_to_address: UUri, request_id: UUID, invoked_method: UUri, ) -> UMessageBuilder

Gets a builder for creating RPC response messages.

A response message is used to send the outcome of processing a request message to the original sender of the request message.

The builder will be initialized with UPriority::UPRIORITY_CS4.

§Arguments

reply_to_address - The URI that the sender of the request expects to receive the response message at.
request_id - The identifier of the request that this is the response to.
invoked_method - The URI identifying the method that has been invoked and which the created message is the outcome of.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address.clone(), request_id.clone(), invoked_method.clone())
                   .build()?;
assert_eq!(message.type_unchecked(), UMessageType::UMESSAGE_TYPE_RESPONSE);
assert_eq!(message.priority_unchecked(), UPriority::UPRIORITY_CS4);
assert_eq!(message.source_unchecked(), &invoked_method);
assert_eq!(message.sink_unchecked(), &reply_to_address);
assert_eq!(message.request_id_unchecked(), &request_id);

Source

pub fn response_for_request(request_attributes: &UAttributes) -> UMessageBuilder

Gets a builder for creating RPC response messages in reply to a request.

A response message is used to send the outcome of processing a request message to the original sender of the request message.

The builder will be initialized with values from the given request attributes.

§Arguments

request_attributes - The attributes from the request message. The response message builder will be initialized with the corresponding attribute values.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUID, UUri};

let method_to_invoke = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_message_id = UUID::build();
let request_message = UMessageBuilder::request(method_to_invoke.clone(), reply_to_address.clone(), 5000)
                          .with_message_id(request_message_id.clone()) // normally not needed, used only for asserts below
                          .build_with_payload("lock", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;

let response_message = UMessageBuilder::response_for_request(&request_message.attributes)
                          .with_priority(UPriority::UPRIORITY_CS5)
                          .build()?;
assert_eq!(response_message.type_unchecked(), UMessageType::UMESSAGE_TYPE_RESPONSE);
assert_eq!(response_message.priority_unchecked(), UPriority::UPRIORITY_CS5);
assert_eq!(response_message.source_unchecked(), &method_to_invoke);
assert_eq!(response_message.sink_unchecked(), &reply_to_address);
assert_eq!(response_message.request_id_unchecked(), &request_message_id);
assert_eq!(response_message.ttl_unchecked(), 5000);

Source

pub fn with_message_id(&mut self, message_id: UUID) -> &mut UMessageBuilder

Sets the message’s identifier.

Every message must have an identifier. If this function is not used, an identifier will be generated and set on the message when one of the build functions is called on the UMessageBuilder.

It’s more typical to not use this function, but could have edge case uses.

§Arguments

message_id - The identifier to use.

§Returns

The builder.

§Panics

Panics if the given UUID is not a valid uProtocol UUID.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUID, UUri};

let topic = UUri::try_from("//my-vehicle/4210/1/B24D")?;
let mut builder = UMessageBuilder::publish(topic);
builder.with_priority(UPriority::UPRIORITY_CS2);
let message_one = builder
                    .with_message_id(UUID::build())
                    .build_with_payload("closed", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
let message_two = builder
                    // use new message ID but retain all other attributes
                    .with_message_id(UUID::build())
                    .build_with_payload("open", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_ne!(message_one.id_unchecked(), message_two.id_unchecked());
assert_eq!(message_one.source_unchecked(), message_two.source_unchecked());
assert_eq!(message_one.priority_unchecked(), UPriority::UPRIORITY_CS2);
assert_eq!(message_two.priority_unchecked(), UPriority::UPRIORITY_CS2);

Source

pub fn with_priority(&mut self, priority: UPriority) -> &mut UMessageBuilder

Sets the message’s priority.

If not set explicitly, the default priority as defined in the uProtocol specification is used.

§Arguments

priority - The priority to be used for sending the message.

§Returns

The builder.

§Panics

if the builder is used for creating an RPC message but the given priority is less than CS4.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let topic = UUri::try_from("//my-vehicle/4210/1/B24D")?;
let message = UMessageBuilder::publish(topic)
                  .with_priority(UPriority::UPRIORITY_CS5)
                  .build_with_payload("closed", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.priority_unchecked(), UPriority::UPRIORITY_CS5);

Source

pub fn with_ttl(&mut self, ttl: u32) -> &mut UMessageBuilder

Sets the message’s time-to-live.

§Arguments

ttl - The time-to-live in milliseconds. The value is capped at i32::MAX.

§Returns

The builder.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_msg_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address, request_msg_id, invoked_method)
                    .with_ttl(2000)
                    .build()?;
assert_eq!(message.ttl_unchecked(), 2000);

Source

pub fn with_token<T: Into<String>>(&mut self, token: T) -> &mut UMessageBuilder

Sets the message’s authorization token used for TAP.

§Arguments

token - The token.

§Returns

The builder.

§Panics

if the message is not an RPC request message

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let method_to_invoke = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let token = String::from("this-is-my-token");
let message = UMessageBuilder::request(method_to_invoke, reply_to_address, 5000)
                    .with_token(token.clone())
                    .build_with_payload("lock", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.token(), Some(&token));

Source

pub fn with_permission_level(&mut self, level: u32) -> &mut UMessageBuilder

Sets the message’s permission level.

§Arguments

level - The level.

§Returns

The builder.

§Panics

if the given level is greater than i32::MAX
if the message is not an RPC request message

§Examples

use up_rust::{UCode, UMessageBuilder, UPayloadFormat, UPriority, UUri};

let method_to_invoke = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let message = UMessageBuilder::request(method_to_invoke, reply_to_address, 5000)
                    .with_permission_level(12)
                    .build_with_payload("lock", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.permission_level(), Some(12));

Source

pub fn with_comm_status(&mut self, comm_status: UCode) -> &mut UMessageBuilder

Sets the message’s communication status.

§Arguments

comm_status - The status.

§Returns

The builder.

§Panics

if the message is not an RPC response message

§Examples

use up_rust::{UCode, UMessageBuilder, UPriority, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_msg_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address, request_msg_id, invoked_method)
                    .with_comm_status(UCode::OK)
                    .build()?;
assert_eq!(message.commstatus_unchecked(), UCode::OK);

Source

pub fn with_traceparent<T: Into<String>>( &mut self, traceparent: T, ) -> &mut UMessageBuilder

Sets the identifier of the W3C Trace Context to convey in the message.

§Arguments

traceparent - The identifier.

§Returns

The builder.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let topic = UUri::try_from("//my-vehicle/4210/1/B24D")?;
let traceparent = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01".to_string();
let message = UMessageBuilder::publish(topic.clone())
                   .with_traceparent(&traceparent)
                   .build_with_payload("closed", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert_eq!(message.traceparent(), Some(&traceparent));

Source

pub fn build(&self) -> Result<UMessage, UMessageError>

Creates the message based on the builder’s state.

§Returns

A message ready to be sent using crate::UTransport::send.

§Errors

If the properties set on the builder do not represent a consistent set of UAttributes, a UMessageError::AttributesValidationError is returned.

§Examples

§Not setting `id` explicitly with [`UMessageBuilder::with_message_id()’]

The recommended way to use the UMessageBuilder.

use up_rust::{UAttributes, UAttributesValidators, UMessageBuilder, UMessageError, UMessageType, UPriority, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let result = UMessageBuilder::response(reply_to_address, UUID::build(), invoked_method)
                    .build();
assert!(result.is_ok());

§Setting `id` explicitly with [`UMessageBuilder::with_message_id()’]

Note that explicitly using [`UMessageBuilder::with_message_id()’] is not required as shown above.

use up_rust::{UMessageBuilder, UMessageType, UPriority, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let message_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address, UUID::build(), invoked_method)
                    .with_message_id(message_id.clone())
                    .build()?;
assert_eq!(message.id_unchecked(), &message_id);

Source

pub fn build_with_payload<T: Into<Bytes>>( &mut self, payload: T, format: UPayloadFormat, ) -> Result<UMessage, UMessageError>

Creates the message based on the builder’s state and some payload.

§Arguments

payload - The data to set as payload.
format - The payload format.

§Returns

A message ready to be sent using crate::UTransport::send.

§Errors

If the properties set on the builder do not represent a consistent set of UAttributes, a UMessageError::AttributesValidationError is returned.

§Examples

use up_rust::{UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UUri};

let topic = UUri::try_from("//my-vehicle/4210/1/B24D")?;
let message = UMessageBuilder::publish(topic)
                   .build_with_payload("locked", UPayloadFormat::UPAYLOAD_FORMAT_TEXT)?;
assert!(message.payload.is_some());

Source

pub fn build_with_protobuf_payload<T: Message>( &mut self, payload: &T, ) -> Result<UMessage, UMessageError>

Creates the message based on the builder’s state and some payload.

§Arguments

payload - The data to set as payload.

§Returns

A message ready to be sent using crate::UTransport::send. The message will have UPayloadFormat::UPAYLOAD_FORMAT_PROTOBUF set as its payload format.

§Errors

If the given payload cannot be serialized into a protobuf byte array, a UMessageError::DataSerializationError is returned. If the properties set on the builder do not represent a consistent set of UAttributes, a UMessageError::AttributesValidationError is returned.

§Examples

use up_rust::{UCode, UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UStatus, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address, request_id, invoked_method)
                   .with_comm_status(UCode::INVALID_ARGUMENT)
                   .build_with_protobuf_payload(&UStatus::fail("failed to parse request"))?;
assert!(message.payload.is_some());
assert_eq!(message.payload_format_unchecked(), UPayloadFormat::UPAYLOAD_FORMAT_PROTOBUF);

Source

pub fn build_with_wrapped_protobuf_payload<T: MessageFull>( &mut self, payload: &T, ) -> Result<UMessage, UMessageError>

Creates the message based on the builder’s state and some payload.

§Arguments

payload - The data to set as payload.

§Returns

A message ready to be sent using crate::UTransport::send. The message will have UPayloadFormat::UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY set as its payload format.

§Errors

If the given payload cannot be serialized into a protobuf byte array, a UMessageError::DataSerializationError is returned. If the properties set on the builder do not represent a consistent set of UAttributes, a UMessageError::AttributesValidationError is returned.

§Examples

use up_rust::{UCode, UMessageBuilder, UMessageType, UPayloadFormat, UPriority, UStatus, UUID, UUri};

let invoked_method = UUri::try_from("//my-vehicle/4210/5/64AB")?;
let reply_to_address = UUri::try_from("//my-cloud/BA4C/1/0")?;
let request_id = UUID::build();
// a service implementation would normally use
// `UMessageBuilder::response_for_request(&request_message.attributes)` instead
let message = UMessageBuilder::response(reply_to_address, request_id, invoked_method)
                   .with_comm_status(UCode::INVALID_ARGUMENT)
                   .build_with_wrapped_protobuf_payload(&UStatus::fail("failed to parse request"))?;
assert!(message.payload.is_some());
assert_eq!(message.payload_format_unchecked(), UPayloadFormat::UPAYLOAD_FORMAT_PROTOBUF_WRAPPED_IN_ANY);