Sample api rework

[milyin]

Closes #837

The API changes proposed by this request are:

1. Implemented set of traits for unified way of constructing sample in publisher and queryable. These traits are:

pub trait QoSBuilderTrait {
    /// Change the `congestion_control` to apply when routing the data.
    fn congestion_control(self, congestion_control: CongestionControl) -> Self;
    /// Change the priority of the written data.
    fn priority(self, priority: Priority) -> Self;
    /// Change the `express` policy to apply when routing the data.
    /// When express is set to `true`, then the message will not be batched.
    /// This usually has a positive impact on latency but negative impact on throughput.
    fn express(self, is_express: bool) -> Self;
}

pub trait TimestampBuilderTrait {
    /// Sets of clears timestamp
    fn timestamp<T: Into<Option<Timestamp>>>(self, timestamp: T) -> Self;
}

pub trait SampleBuilderTrait {
    /// Attach source information
    #[zenoh_macros::unstable]
    fn source_info(self, source_info: SourceInfo) -> Self;
    /// Attach user-provided data in key-value format
    #[zenoh_macros::unstable]
    fn attachment<T: Into<Option<Attachment>>>(self, attachment: T) -> Self;
}

pub trait ValueBuilderTrait {
    /// Set the [`Encoding`]
    fn encoding<T: Into<Encoding>>(self, encoding: T) -> Self;
    /// Sets the payload
    fn payload<T: Into<Payload>>(self, payload: T) -> Self;
    /// Sets both payload and encoding at once.
    /// This is convenient for passing user type which supports `Into<Value>` when both payload and encoding depends on user type
    fn value<T: Into<Value>>(self, value: T) -> Self;
}

Depending on the component, specific traits are implemented. For example builder for Session::put operation mplements QoSBuilderTrait + SampleBuilderTrait + ValueBuilderTrait, but builder for Publisher::delete implements only SampleBuilderTrait, because priority is set in publisher itself (trait QoSBuilderTrait is implemented by the PublisherBuilder) and encoding and payload are not sent on delete operation.

This allows to guarantee consistent support of sample data in different components.

TimestampBuilderTrait is separate because get operation doesn't support sending timestamp, so it was necessary to detach this function from others

2. removed write access to Sample structure. Implemented builders SampleBuilder, PutSampleBuilder, DeleteSampleBuilder instead. These builders may be constructed either empty or from existing sample. They are implemented as a wrappers around Sample, so sample can be edited on place.

Example:

// ensure the sample has a timestamp, thus it will always be sorted into the MergeQueue
// after any timestamped Sample possibly coming from a fetch reply.
let s = if s.timestamp().is_none() {
  SampleBuilder::from(s).with_timestamp(new_reception_timestamp()).into()
} else {
  s
};

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[eclipse-zenoh-bot]

@milyin If this pull request contains a bugfix or a new feature, then please consider using Closes #ISSUE-NUMBER syntax to link it to an issue.

[Mallets]

Value has not been ported yet to accessor pattern.
By implementing ValueBuilderTrait directly on Value we will have a conflict in terms of functions.

With accessor pattern:

let payload: &Payload = value.payload();

With builder pattern:

value = value.payload("foo");

Do we really need to implement ValueBuilderTrait on Value itself or could we have a ValueBuilder as we do with a SampleBuilder?

[milyin]

I think yes, the separate builder wrapper structure is the only way to have same names for builder parameters and for data accessors. So if we have this SampleBuilder, the ValueBuildershould appear too

[milyin]

But I think it's would be easier to make value accessors and value builder in a separate PR