ObjectLifecycleController

open class ObjectLifecycleController : Controller

Keeps track of agents or specific Coaty objects in a Coaty network by monitoring agent identities or custom object types.

This controller observes advertisements and deadvertisements of such objects and discovers them. Changes are emitted on corresponding observables that applications can subscribe to.

You can use this controller either standalone by adding it to the container components or extend your custom controller class from this controller class.

If you want to keep track of custom object types (not agent identities), you have to implement the remote side of the distributed object lifecycle management explicitely, i.e. advertise/readvertise/deadvertise your custom objects and observe/resolve corresponding Discover events. To facilitate this, this controller provides convenience methods: advertiseDiscoverableObject, readvertiseDiscoverableObject, and deadvertiseDiscoverableObject.

Usually, a custom object should have the object ID of its agent identity, i.e. Container.identity, set as its parentObjectId in order to be automatically deadvertised when the agent terminates abnormally. You can automate this by passing true to the optional parameter shouldSetParentObjectId of method advertiseDiscoverableObject (true is also the default parameter value).

Public methods

  • Observes advertisements, deadvertisments and initial discoveries of objects of the given core type. To track agent identity objects, specify core type Identity.

    Specify an optional filter predicate to be applied to trackable objects. If the predicate function returns true, the object is being tracked; otherwise the object is not tracked. If no predicate is specified, all objects corresponding to the given core type are tracked.

    Remark

    Subscriptions to the returned observable are automatically unsubscribed when the communication manager is stopped.

    Declaration

    Swift

    public func observeObjectLifecycleInfoByCoreType(coreType: CoreType,
                                                 objectFilter: ((CoatyObject) -> Bool)? = nil) -> Observable<ObjectLifecycleInfo>

    Parameters

    coreType

    the core type of objects to be tracked
    objectFilter

    a predicate for filtering objects to be tracked (optional)

    Return Value

    an observable emitting changes concerning tracked objects of the given core type

  • Observes advertisements, deadvertisments and initial discoveries of objects of the given object type.

    Specify an optional filter predicate to be applied to trackable objects. If the predicate function returns true, the object is being tracked; otherwise the object is not tracked. If no predicate is specified, all objects corresponding to the given core type are tracked.

    Remark

    Subscriptions to the returned observable are automatically unsubscribed when the communication manager is stopped.

    Declaration

    Swift

    public func observeObjectLifecycleInfoByObjectType(with objectType: String,
                                                   objectFilter: ((CoatyObject) -> Bool)? = nil) -> Observable<ObjectLifecycleInfo>

    Parameters

    objectType

    the object type of objects to be tracked
    objectFilter

    a predicate for filtering objects to be tracked (optional)

    Return Value

    an observable emitting changes concerning tracked objects of the given object type

  • Advertises the given Coaty object and makes it discoverable either by its objectType or objectId.

    The optional shouldSetParentObjectId parameter determines whether the parent object ID of the given object should be set to the agent identity’s object ID (default is true). This is required if you want to observe the object’s lifecycle info by method observeObjectLifecycleInfoByObjectType and to get notified when the advertising agent terminates abnormally.

    The returned subscription should be unsubscribed when the object is deadvertised explicitely in your application code (see method deadvertiseDiscoverableObject). It will be automatically unsubscribed when the communication manager is stopped.

    Declaration

    Swift

    public func advertiseDiscoverableObject(object: CoatyObject,
                                        shouldSetParentObjectId: Bool = true) -> Disposable

    Parameters

    object

    a CoatyObject that is advertised and discoverable
    shouldSetParentObjectId

    determines whether the parent object ID of the given object should be set to the agent identity’s object ID (default is true)

    Return Value

    the subscription (of type Disposable) on a DiscoverEvent observable that should be disposed (unsubscribed) if no longer needed

  • Readvertises the given Coaty object, usually after some properties have changed. The object reference should have been advertised before once using the method advertiseDiscoverableObject.

    Declaration

    Swift

    public func readvertiseDiscoverableObject(object: CoatyObject)

    Parameters

    object

    a CoatyObject that should be advertised again after properties have changed

  • Deadvertises the given Coaty object and unsubscribes the given subscription resulting from a corresponding invocation of method advertiseDiscoverableObject.

    Note that if you want to keep a Coaty object for the whole lifetime of its agent you don’t necessarily need to invoke this method explicitely. Deadvertise events are published automatically by or on behalf of an agent whenever its communication manager is stopped or when the agent terminates abnormally.

    Declaration

    Swift

    public func deadvertiseDiscoverableObject(object: CoatyObject,
                                          discoverableSubscription: Disposable)

    Parameters

    object

    a CoatyObject to be deadvertised
    discoverableSubscription

    subscription on DiscoverEvent to be unsubscribed