CommunicationManager

public class CommunicationManager

Provides a set of predefined communication events to transfer Coaty objects between distributed Coaty agents based on the publish-subscribe API of a CommunicationClient.

Properties.

  • Gets the namespace for communication as specified in the configuration options. Returns the default namespace used, if no namespace has been specified in configuration options.

    Declaration

    Swift

    private(set) public var namespace: String { get }

  • Undocumented

    Declaration

    Swift

    public var identity: Identity

Initializers.

Manager lifecycle methods.

  • Starts this communication manager with the communication options specified in the configuration. This is a noop if the communication manager has already been started.

    Declaration

    Swift

    public func start()

  • Stops dispatching and emitting communication events and disconnects from the communication infrastructure.

    To continue processing with this communication manager sometime later, invoke start().

    Declaration

    Swift

    public func stop()

  • Unsubscribe and disconnect from the communication binding.

    Declaration

    Swift

    public func onDispose()

IO Routing

  • Gets the IO node for the given IO context name, as configured in the configuration common options.

    Returns nil if no IO node is configured for the context name.

    Declaration

    Swift

    public func getIoNodeByContext(contextName: String) -> IoNode?

  • Creates a new IO route for routing IO values of the given IO source to associated IO actors.

    This method is called by IO routers to associate IO sources with IO actors. An IO source publishes IO values on this route; an associated IO actor observes this route to receive these values.

    Declaration

    Swift

    public func createIoRoute(ioSource: IoSource) -> String

    Parameters

    ioSource

    the IO source object

    Return Value

    an associating topic for routing IO values

  • Observe communication state changes.

    When subscribed the observable immediately emits the current communication state.

    Declaration

    Swift

    public func observeCommunicationState() -> Observable<CommunicationState>

    Return Value

    an observable emitting communication states

One way events.

  • Observes incoming messages on a raw subscription topic.

    The topic filter must be a non-empty string that does not contain the character NULL (U+0000).

    Use this method to interoperate with external systems that publish messages on external topics. Use this method together with publishRaw() to transfer binary data between Coaty agents.

    In order to decode [UInt8] array named data into String use String(bytes: data, encoding: .utf8)

    Throws

    if topic filter is invalid

    Declaration

    Swift

    public func observeRaw(topicFilter: String) throws -> Observable<(String, [UInt8])>

    Parameters

    topicFilter

    the subscription topic

    Return Value

    an observable emitting any incoming messages as tuples containing the actual topic and the payload as a UInt8 Array

  • Observe Advertise events for the given core type.

    Declaration

    Swift

    public func observeAdvertise(withCoreType: CoreType) -> Observable<AdvertiseEvent>

    Parameters

    coreType

    coreType core type of objects to be observed

    Return Value

    an observable emitting incoming Advertise events for the given core type

  • Observe Advertise events for the given object type.

    The given object type must be a non-empty string that does not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B), / (U+002F).

    Throws

    if object type is invalid

    Declaration

    Swift

    public func observeAdvertise(withObjectType: String) throws -> Observable<AdvertiseEvent>

    Parameters

    objectType

    objectType object type of objects to be observed

    Return Value

    an observable emitting incoming Advertise events for the given object type

  • Observe Deadvertise events.

    Declaration

    Swift

    public func observeDeadvertise() -> Observable<DeadvertiseEvent>

    Return Value

    an observable emitting incoming Deadvertise events

  • Observe Channel events for the given channel identifier.

    The channel identifier must be a non-empty string that does not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B), / (U+002F).

    Throws

    if channel identifier is invalid

    Declaration

    Swift

    public func observeChannel(channelId: String) throws -> Observable<ChannelEvent>

    Parameters

    channelId

    a channel identifier

    Return Value

    an observable emitting incoming Channel events for the given channel identifier

Two way events.

  • Observe Update events for the given core type.

    Declaration

    Swift

    public func observeUpdate(withCoreType: CoreType) -> Observable<UpdateEvent>

    Parameters

    coreType

    coreType core type of objects to be observed

    Return Value

    an observable emitting incoming Update events for the given core type

  • Observe Update events for the given object type.

    The given object type must be a non-empty string that does not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B), / (U+002F).

    Throws

    if object type is invalid

    Declaration

    Swift

    public func observeUpdate(withObjectType: String) throws -> Observable<UpdateEvent>

    Parameters

    objectType

    objectType object type of objects to be observed

    Return Value

    an observable emitting incoming Update events for the given object type

  • Observe Discover events.

    Declaration

    Swift

    public func observeDiscover() -> Observable<DiscoverEvent>

    Return Value

    an observable emitting incoming Discover events

  • Observe Call events for the given operation and context object.

    The operation name must be a non-empty string that does not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B), / (U+002F).

    The given context object is matched against the context filter specified in incoming Call event data to determine whether the Call event should be emitted or skipped by the observable.

    A Call event is not emitted by the observable if:

    • context filter and context object are both specified and they do not match (checked by using ObjectMatcher.matchesFilter), or
    • context filter is not supplied and context object is specified.

    In all other cases, the Call event is emitted.

    Note

    You can also invoke observeCall without context parameter and realize a custom matching logic with an RxJS filter operator.

    Throws

    if operationId is invalid

    Declaration

    Swift

    public func observeCall(operationId: String, context: CoatyObject?) throws -> Observable<CallEvent>

    Parameters

    operationId

    the name of the operation to be invoked
    context

    a context object to be matched against the Call event data’s context filter (optional)

    Return Value

    an observable emitting incoming Call events whose context filter matches the given context

  • Observe Query events.

    Declaration

    Swift

    public func observeQuery() throws -> Observable<QueryEvent>

    Return Value

    an observable emitting incoming Query events

IO Routing

  • Observe IO state events for the given IO source or actor.

    When subscribed the subject immediately emits the current association state.

    Subscriptions to the returned subject are automatically unsubscribed when the communication manager is stopped, in order to release system resources and to avoid memory leaks.

    Declaration

    Swift

    public func observeIoState(ioPoint: IoPoint) -> BehaviorSubject<IoStateEvent>

    Return Value

    a subject emitting IO state events for the given IO source or actor

  • Observe IO values for the given IO actor.

    Depending on the data format specification of the IO actor (IoActor.useRawIoValues), values emitted by the observable are either raw binary ([UInt8] array) or decoded as JSON objects (Any type).

    Subscriptions to the returned observable are automatically unsubscribed when the communication manager is stopped, in order to release system resources and to avoid memory leaks.

    Declaration

    Swift

    public func observeIoValue(ioActor: IoActor) -> Observable<Any>

    Return Value

    an observable emitting inbound values for the IO actor

One way events.

  • Publish a value on the given topic. Used to interoperate with external clients that subscribe on the given topic.

    The topic is an MQTT publication topic, i.e. a non-empty string that must not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B).

    Throws

    if topic name is invalid

    Declaration

    Swift

    @available(*, deprecated)
public func publishRaw(topic: String, value: String) throws

    Parameters

    topic

    the topic on which to publish the given payload
    value

    a payload string to be published on the given topic

  • Publish a value on the given topic. Used to interoperate with external clients that subscribe on the given topic.

    The topic is an MQTT publication topic, i.e. a non-empty string that must not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B).

    Throws

    if topic name is invalid

    Declaration

    Swift

    public func publishRaw(topic: String, withString value: String) throws

    Parameters

    topic

    the topic on which to publish the given payload
    withString

    a payload string to be published on the given topic

  • Publish a value on the given topic. Used to interoperate with external clients that subscribe on the given topic.

    The topic is an MQTT publication topic, i.e. a non-empty string that must not contain the following characters: NULL (U+0000), # (U+0023), + (U+002B).

    Throws

    if topic name is invalid

    Declaration

    Swift

    public func publishRaw(topic: String, withBinary value: [UInt8]) throws

    Parameters

    topic

    the topic on which to publish the given payload
    withBinary

    a payload bytes array to be published on the given topic

  • Advertise an object.

    Declaration

    Swift

    public func publishAdvertise(_ event: AdvertiseEvent)

    Parameters

    advertiseEvent

    the Advertise event to be published

  • Notify subscribers that an advertised object has been deadvertised.

    Declaration

    Swift

    public func publishDeadvertise(_ event: DeadvertiseEvent)

    Parameters

    deadvertiseEvent

    the Deadvertise event to be published

  • Publish a Channel event.

    Declaration

    Swift

    public func publishChannel(_ event: ChannelEvent)

    Parameters

    event

    the Channel event to be published

Two way events.

  • Request or propose an update of the specified object and receive accomplishments.

    Note that after all initial subscribers have unsubscribed from the returned observable no more response events will be emitted on the observable and an error event will be emitted on resubscription.

    Todo

    Implement the lazy publishing behavior (not until the first subscription)

    Declaration

    Swift

    public func publishUpdate(_ event: UpdateEvent) -> Observable<CompleteEvent>

    Parameters

    event

    the Update event to be published

    Return Value

    an observable on which associated Complete events are emitted

  • Find discoverable objects and receive Resolve events for them.

    Note that after all initial subscribers have unsubscribed from the returned observable no more response events will be emitted on the observable and an error event will be emitted on resubscription.

    Todo

    Implement the lazy publishing behavior (not until the first subscription)

    Declaration

    Swift

    public func publishDiscover(_ event: DiscoverEvent) -> Observable<ResolveEvent>

    Parameters

    event

    the Discover event to be published.

    Return Value

    an observable on which associated Resolve events are emitted

  • Find queryable objects and receive Retrieve events for them.

    Note that after all initial subscribers have unsubscribed from the returned observable no more response events will be emitted on the observable and an error event will be emitted on resubscription.

    Todo

    Implement the lazy publishing behavior (not until the first subscription)

    Declaration

    Swift

    public func publishQuery(_ event: QueryEvent) -> Observable<RetrieveEvent>

    Parameters

    event

    the Query event to be published

    Return Value

    an observable on which associated Retrieve events are emitted.

  • Publish a Call event to perform a remote operation and receive results emitted by the observable returned.

    Note that after all initial subscribers have unsubscribed from the returned observable no more response events will be emitted on the observable and an error event will be emitted on resubscription.

    Declaration

    Swift

    public func publishCall(_ event: CallEvent) -> Observable<ReturnEvent>

    Parameters

    event

    the Call event to be published.

    Return Value

    an observable of associated Return events.

IO Routing

  • Publish the given IoValue event.

    No publication is performed if the event’s IO source is currently not associated with any IO actor.

    Declaration

    Swift

    public func publishIoValue(event: IoValueEvent)

    Parameters

    event

    the IoValue event for publishing

Utility methods.