Struct UMessageBuilder

pub struct UMessageBuilder<S: BuilderState> { /* private fields */ }

A builder for creating UMessages.

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

For each type of message there is a dedicated builder which ensures that only attributes relevant to that message type are set.

Implementations

impl UMessageBuilder<InitialBuilderState>

pub fn publish(topic: UUri) -> UMessageBuilder<PublishBuilderState>

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::Text)?;
assert_eq!(message.type_(), UMessageType::Publish);
assert!(message.priority().is_none());
assert_eq!(message.source(), &topic);

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

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::Text)?;
assert_eq!(message.type_(), UMessageType::Notification);
assert!(message.priority().is_none());
assert_eq!(message.source(), &origin);
assert_eq!(message.sink_unchecked(), &destination);

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

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::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::Text)?;
assert_eq!(message.type_(), UMessageType::Request);
assert_eq!(message.priority_unchecked(), UPriority::CS4);
assert_eq!(message.source(), &reply_to_address);
assert_eq!(message.sink_unchecked(), &method_to_invoke);
assert_eq!(message.ttl_unchecked(), 5000);

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

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::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_(), UMessageType::Response);
assert_eq!(message.priority_unchecked(), UPriority::CS4);
assert_eq!(message.source(), &invoked_method);
assert_eq!(message.sink_unchecked(), &reply_to_address);
assert_eq!(message.request_id_unchecked(), &request_id);

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

Gets a builder for creating an RPC response message 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.

Panics

if the given attributes do not represent a request message.

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::Text)?;

let response_message = UMessageBuilder::response_for_request(request_message.attributes())
                          .with_priority(UPriority::CS5)
                          .build()?;
assert_eq!(response_message.type_(), UMessageType::Response);
assert_eq!(response_message.priority_unchecked(), UPriority::CS5);
assert_eq!(response_message.source(), &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);

impl<S: BuilderState> UMessageBuilder<S>

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

Sets the message’s identifier.

Every message must have an identifier. However, if this function is not used, an identifier will be generated for the message when one of the build functions is called.

This method is mainly useful for implementing tests that include assertions on the message ID.

Arguments

• message_id - The identifier to use.

Returns

The builder.

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);
let message_one = builder
                    .with_message_id(UUID::build())
                    .build_with_payload("closed", UPayloadFormat::Text)?;
let message_two = builder
                    // use new message ID but retain all other attributes
                    .with_message_id(UUID::build())
                    .build_with_payload("open", UPayloadFormat::Text)?;
assert_ne!(message_one.id(), message_two.id());
assert_eq!(message_one.source(), message_two.source());
assert_eq!(message_one.payload_format_unchecked(), message_two.payload_format_unchecked());

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

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.

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::CS5)
                  .build_with_payload("closed", UPayloadFormat::Text)?;
assert_eq!(message.priority_unchecked(), UPriority::CS5);

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

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);

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

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";
let message = UMessageBuilder::publish(topic.clone())
                   .with_traceparent(traceparent)
                   .build_with_payload("closed", UPayloadFormat::Text)?;
assert_eq!(message.traceparent(), Some(traceparent));

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(), &message_id);

pub fn build_with_payload_encoding<T: Into<Bytes>>( &mut self, payload: T, encoding: PayloadEncoding, ) -> Result<UMessage, UMessageError>

Creates the message based on the builder’s state and a payload labeled with an open payload-encoding identity.

Reserved-range encodings produce the same attributes as Self::build_with_payload. Other encodings populate the open payload-encoding identity fields and leave payload_format unspecified.

Errors

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

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::Text)?;
assert!(message.payload().is_some());

pub fn build_with_protobuf_payload<T: ProtobufMappable>( &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::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 protobuf::well_known_types::wrappers::StringValue;
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 payload = StringValue::new();
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::InvalidArgument)
                   .build_with_protobuf_payload(&payload)?;
assert!(message.payload().is_some());
assert_eq!(message.payload_format_unchecked(), UPayloadFormat::Protobuf);

pub fn build_with_wrapped_protobuf_payload<T: ProtobufMappable>( &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::ProtobufWrappedInAny 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 protobuf::well_known_types::wrappers::StringValue;
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 payload = StringValue::new();
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::InvalidArgument)
                   .build_with_wrapped_protobuf_payload(&payload)?;
assert!(message.payload().is_some());
assert_eq!(message.payload_format_unchecked(), UPayloadFormat::ProtobufWrappedInAny);

impl UMessageBuilder<RequestBuilderState>

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

Sets the message’s authorization token used for TAP.

Arguments

• token - The token.

Returns

The builder.

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 = "this-is-my-token";
let message = UMessageBuilder::request(method_to_invoke, reply_to_address, 5000)
                    .with_token(token)
                    .build_with_payload("lock", UPayloadFormat::Text)?;
assert_eq!(message.token(), Some(token));

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

Sets the message’s permission level.

Arguments

• level - The level.

Returns

The builder.

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::Text)?;
assert_eq!(message.permission_level(), Some(12));

impl UMessageBuilder<ResponseBuilderState>

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

Sets the message’s communication status.

Arguments

• comm_status - The status.

Returns

The builder.

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);

Trait Implementations

impl<S: BuilderState> Debug for UMessageBuilder<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.