path: root/src/subscription_listener.rs

use crate::item_update::ItemUpdate;

/// Interface to be implemented to listen to Subscription events comprehending notifications
/// of subscription/unsubscription, updates, errors and others.
///
/// Events for these listeners are dispatched by a different thread than the one that generates them.
/// This means that, upon reception of an event, it is possible that the internal state of the client
/// has changed. On the other hand, all the notifications for a single LightstreamerClient,
/// including notifications to ClientListener, SubscriptionListener and ClientMessageListener
/// will be dispatched by the same thread.
pub trait SubscriptionListener: Send {
    /// Event handler that is called by Lightstreamer each time a request to clear the snapshot
    /// pertaining to an item in the Subscription has been received from the Server.
    /// More precisely, this kind of request can occur in two cases:
    ///
    /// - For an item delivered in COMMAND mode, to notify that the state of the item becomes empty;
    ///   this is equivalent to receiving an update carrying a DELETE command once for each key
    ///   that is currently active.
    ///
    /// - For an item delivered in DISTINCT mode, to notify that all the previous updates received
    ///   for the item should be considered as obsolete; hence, if the listener were showing a list
    ///   of recent updates for the item, it should clear the list in order to keep a coherent view.
    ///
    /// Note that, if the involved Subscription has a two-level behavior enabled
    /// (see `Subscription::set_command_second_level_fields()` and
    /// `Subscription::set_command_second_level_field_schema()`), the notification refers to the
    /// first-level item (which is in COMMAND mode). This kind of notification is not possible
    /// for second-level items (which are in MERGE mode).
    ///
    /// # Parameters
    ///
    /// - `item_name`: name of the involved item. If the Subscription was initialized using an
    ///   "Item Group" then a `None` value is supplied.
    /// - `item_pos`: 1-based position of the item within the "Item List" or "Item Group".
    fn on_clear_snapshot(&mut self, _item_name: Option<&str>, _item_pos: usize) {
        // Default implementation does nothing.
        unimplemented!("Implement on_clear_snapshot method for SubscriptionListener.");
    }

    /// Event handler that is called by Lightstreamer to notify that, due to internal resource
    /// limitations, Lightstreamer Server dropped one or more updates for an item that was
    /// subscribed to as a second-level subscription. Such notifications are sent only if the
    /// Subscription was configured in unfiltered mode (second-level items are always in "MERGE"
    /// mode and inherit the frequency configuration from the first-level Subscription).
    ///
    /// By implementing this method it is possible to perform recovery actions.
    ///
    /// # Parameters
    ///
    /// - `lost_updates`: The number of consecutive updates dropped for the item.
    /// - `key`: The value of the key that identifies the second-level item.
    ///
    /// # See also
    ///
    /// - `Subscription::set_requested_max_frequency()`
    /// - `Subscription::set_command_second_level_fields()`
    /// - `Subscription::set_command_second_level_field_schema()`
    fn on_command_second_level_item_lost_updates(&mut self, _lost_updates: u32, _key: &str) {
        // Default implementation does nothing.
        unimplemented!(
            "Implement on_command_second_level_item_lost_updates method for SubscriptionListener."
        );
    }

    /// Event handler that is called when the Server notifies an error on a second-level subscription.
    ///
    /// By implementing this method it is possible to perform recovery actions.
    ///
    /// # Parameters
    ///
    /// - `code`: The error code sent by the Server. It can be one of the following:
    ///   - 14 - the key value is not a valid name for the Item to be subscribed; only in this case,
    ///     the error is detected directly by the library before issuing the actual request to the Server
    ///   - 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
    ///   - 21 - bad Group name
    ///   - 22 - bad Group name for this Schema
    ///   - 23 - bad Schema name
    ///   - 24 - mode not allowed for an Item
    ///   - 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item
    ///   - 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item
    ///   - 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only)
    ///   - 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
    ///   - 68 - the Server could not fulfill the request because of an internal error.
    ///   - `<= 0` - the Metadata Adapter has refused the subscription or unsubscription request;
    ///     the code value is dependent on the specific Metadata Adapter implementation
    /// - `message`: The description of the error sent by the Server; it can be `None`.
    /// - `key`: The value of the key that identifies the second-level item.
    ///
    /// # See also
    ///
    /// - `ConnectionDetails::set_adapter_set()`
    /// - `Subscription::set_command_second_level_fields()`
    /// - `Subscription::set_command_second_level_field_schema()`
    fn on_command_second_level_subscription_error(
        &mut self,
        _code: i32,
        _message: Option<&str>,
        _key: &str,
    ) {
        // Default implementation does nothing.
        unimplemented!(
            "Implement on_command_second_level_subscription_error method for SubscriptionListener."
        );
    }

    /// Event handler that is called by Lightstreamer to notify that all snapshot events for an item
    /// in the Subscription have been received, so that real time events are now going to be received.
    /// The received snapshot could be empty. Such notifications are sent only if the items are delivered
    /// in DISTINCT or COMMAND subscription mode and snapshot information was indeed requested for the items.
    /// By implementing this method it is possible to perform actions which require that all the initial
    /// values have been received.
    ///
    /// Note that, if the involved Subscription has a two-level behavior enabled
    /// (see `Subscription::set_command_second_level_fields()` and
    /// `Subscription::set_command_second_level_field_schema()`), the notification refers to the
    /// first-level item (which is in COMMAND mode). Snapshot-related updates for the second-level
    /// items (which are in MERGE mode) can be received both before and after this notification.
    ///
    /// # Parameters
    ///
    /// - `item_name`: name of the involved item. If the Subscription was initialized using an
    ///   "Item Group" then a `None` value is supplied.
    /// - `item_pos`: 1-based position of the item within the "Item List" or "Item Group".
    ///
    /// # See also
    ///
    /// - `Subscription::set_requested_snapshot()`
    /// - `ItemUpdate::is_snapshot()`
    fn on_end_of_snapshot(&mut self, _item_name: Option<&str>, _item_pos: usize) {
        // Default implementation does nothing.
        unimplemented!("Implement on_end_of_snapshot method for SubscriptionListener.");
    }

    /// Event handler that is called by Lightstreamer to notify that, due to internal resource
    /// limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription.
    /// Such notifications are sent only if the items are delivered in an unfiltered mode; this occurs if the subscription mode is:
    ///
    /// - RAW
    /// - MERGE or DISTINCT, with unfiltered dispatching specified
    /// - COMMAND, with unfiltered dispatching specified
    /// - COMMAND, without unfiltered dispatching specified (in this case, notifications apply to ADD and DELETE events only)
    ///
    /// By implementing this method it is possible to perform recovery actions.
    ///
    /// # Parameters
    ///
    /// - `item_name`: name of the involved item. If the Subscription was initialized using an
    ///   "Item Group" then a `None` value is supplied.
    /// - `item_pos`: 1-based position of the item within the "Item List" or "Item Group".
    /// - `lost_updates`: The number of consecutive updates dropped for the item.
    ///
    /// # See also
    ///
    /// - `Subscription::set_requested_max_frequency()`
    fn on_item_lost_updates(
        &mut self,
        _item_name: Option<&str>,
        _item_pos: usize,
        _lost_updates: u32,
    ) {
        // Default implementation does nothing.
        unimplemented!("Implement on_item_lost_updates method for SubscriptionListener.");
    }

    /// Event handler that is called by Lightstreamer each time an update pertaining to an item
    /// in the Subscription has been received from the Server.
    ///
    /// # Parameters
    ///
    /// - `update`: a value object containing the updated values for all the fields, together with
    ///   meta-information about the update itself and some helper methods that can be used to
    ///   iterate through all or new values.
    fn on_item_update(&self, _update: &ItemUpdate) {
        // Default implementation does nothing.
        unimplemented!("Implement on_item_update method for SubscriptionListener.");
    }

    /// Event handler that receives a notification when the `SubscriptionListener` instance is
    /// removed from a `Subscription` through `Subscription::remove_listener()`. This is the last
    /// event to be fired on the listener.
    fn on_listen_end(&mut self) {
        // Default implementation does nothing.
    }

    /// Event handler that receives a notification when the `SubscriptionListener` instance is
    /// added to a `Subscription` through `Subscription::add_listener()`. This is the first event
    /// to be fired on the listener.
    fn on_listen_start(&mut self) {
        // Default implementation does nothing.
    }

    /// Event handler that is called by Lightstreamer to notify the client with the real maximum
    /// update frequency of the Subscription. It is called immediately after the Subscription is
    /// established and in response to a requested change (see `Subscription::set_requested_max_frequency()`).
    /// Since the frequency limit is applied on an item basis and a Subscription can involve multiple
    /// items, this is actually the maximum frequency among all items. For Subscriptions with two-level
    /// behavior (see `Subscription::set_command_second_level_fields()` and
    /// `Subscription::set_command_second_level_field_schema()`), the reported frequency limit applies
    /// to both first-level and second-level items.
    ///
    /// The value may differ from the requested one because of restrictions operated on the server side,
    /// but also because of number rounding.
    ///
    /// Note that a maximum update frequency (that is, a non-unlimited one) may be applied by the Server
    /// even when the subscription mode is RAW or the Subscription was done with unfiltered dispatching.
    ///
    /// # Parameters
    ///
    /// - `frequency`: A decimal number, representing the maximum frequency applied by the Server
    ///   (expressed in updates per second), or the string "unlimited". A `None` value is possible in
    ///   rare cases, when the frequency can no longer be determined.
    fn on_real_max_frequency(&mut self, _frequency: Option<f64>) {
        // Default implementation does nothing.
        unimplemented!("Implement on_real_max_frequency method for SubscriptionListener.");
    }

    /// Event handler that is called by Lightstreamer to notify that a Subscription has been successfully
    /// subscribed to through the Server. This can happen multiple times in the life of a Subscription
    /// instance, in case the Subscription is performed multiple times through `LightstreamerClient::unsubscribe()`
    /// and `LightstreamerClient::subscribe()`. This can also happen multiple times in case of automatic
    /// recovery after a connection restart.
    ///
    /// This notification is always issued before the other ones related to the same subscription.
    /// It invalidates all data that has been received previously.
    ///
    /// Note that two consecutive calls to this method are not possible, as before a second
    /// `on_subscription` event is fired an `on_unsubscription()` event is eventually fired.
    ///
    /// If the involved Subscription has a two-level behavior enabled
    /// (see `Subscription::set_command_second_level_fields()` and
    /// `Subscription::set_command_second_level_field_schema()`), second-level subscriptions are not notified.
    fn on_subscription(&mut self) {
        // Default implementation does nothing.
    }

    /// Event handler that is called when the Server notifies an error on a Subscription.
    /// By implementing this method it is possible to perform recovery actions.
    ///
    /// Note that, in order to perform a new subscription attempt, `LightstreamerClient::unsubscribe()`
    /// and `LightstreamerClient::subscribe()` should be issued again, even if no change to the
    /// Subscription attributes has been applied.
    ///
    /// # Parameters
    ///
    /// - `code`: The error code sent by the Server. It can be one of the following:
    ///   - 15 - "key" field not specified in the schema for a COMMAND mode subscription
    ///   - 16 - "command" field not specified in the schema for a COMMAND mode subscription
    ///   - 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set
    ///   - 21 - bad Group name
    ///   - 22 - bad Group name for this Schema
    ///   - 23 - bad Schema name
    ///   - 24 - mode not allowed for an Item
    ///   - 25 - bad Selector name
    ///   - 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item
    ///   - 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item
    ///   - 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only)
    ///   - 29 - RAW mode is not allowed by the current license terms (for special licenses only)
    ///   - 30 - subscriptions are not allowed by the current license terms (for special licenses only)
    ///   - 66 - an unexpected exception was thrown by the Metadata Adapter while authorizing the connection
    ///   - 68 - the Server could not fulfill the request because of an internal error.
    ///   - `<= 0` - the Metadata Adapter has refused the subscription or unsubscription request;
    ///     the code value is dependent on the specific Metadata Adapter implementation
    /// - `message`: The description of the error sent by the Server; it can be `None`.
    ///
    /// # See also
    ///
    /// - `ConnectionDetails::set_adapter_set()`
    fn on_subscription_error(&mut self, _code: i32, _message: Option<&str>) {
        // Default implementation does nothing.
        unimplemented!("Implement on_subscription_error method for SubscriptionListener.");
    }

    /// Event handler that is called by Lightstreamer to notify that a Subscription has been successfully
    /// unsubscribed from. This can happen multiple times in the life of a Subscription instance, in case
    /// the Subscription is performed multiple times through `LightstreamerClient::unsubscribe()` and
    /// `LightstreamerClient::subscribe()`. This can also happen multiple times in case of automatic
    /// recovery after a connection restart.
    ///
    /// After this notification no more events can be received until a new `on_subscription` event.
    ///
    /// Note that two consecutive calls to this method are not possible, as before a second
    /// `on_unsubscription` event is fired an `on_subscription()` event is eventually fired.
    ///
    /// If the involved Subscription has a two-level behavior enabled
    /// (see `Subscription::set_command_second_level_fields()` and
    /// `Subscription::set_command_second_level_field_schema()`), second-level unsubscriptions are not notified.
    fn on_unsubscription(&mut self) {
        // Default implementation does nothing.
    }
}