268 lines
15 KiB
Rust
268 lines
15 KiB
Rust
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 {
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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(&mut self, update: ItemUpdate) {
|
|
// Default implementation does nothing.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
|
|
/// 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.
|
|
}
|
|
} |