From 7e20dd7d488c2987ef6977f4ec5fbdc80daf9127 Mon Sep 17 00:00:00 2001 From: AKosylo Date: Fri, 8 Sep 2023 17:59:08 +0200 Subject: [PATCH] add documentations for API --- DXFeedFramework/Api/DXEndpointObserver.swift | 6 +++ DXFeedFramework/Api/DXEndpointState.swift | 6 +++ DXFeedFramework/Api/DXEventListener.swift | 7 ++- DXFeedFramework/Api/DXFeedSubcription.swift | 49 ++++++++++++++++++- DXFeedFramework/Api/DXPublisher.swift | 3 ++ .../Api/Osub/IObservableSubscription.swift | 16 ++++++ .../Osub/IndexedEventSubscriptionSymbol.swift | 23 ++++++++- DXFeedFramework/Api/Osub/String+Symbol.swift | 1 + DXFeedFramework/Api/Osub/Symbol.swift | 5 ++ .../Osub/TimeSeriesSubscriptionSymbol.swift | 26 ++++++++-- DXFeedFramework/Api/Osub/WildcardSymbol.swift | 27 +++++++++- .../Subscription/NativeSubscription.swift | 18 +++++++ 12 files changed, 178 insertions(+), 9 deletions(-) diff --git a/DXFeedFramework/Api/DXEndpointObserver.swift b/DXFeedFramework/Api/DXEndpointObserver.swift index 2f0285886..3c51b66a9 100644 --- a/DXFeedFramework/Api/DXEndpointObserver.swift +++ b/DXFeedFramework/Api/DXEndpointObserver.swift @@ -7,6 +7,12 @@ import Foundation +/// Notifies a change in the state of this endpoint. public protocol DXEndpointObserver { + /// Fired when state changed + /// + /// - Parameters: + /// - old: The old state of endpoint + /// - new: The new state of endpoint func endpointDidChangeState(old: DXEndpointState, new: DXEndpointState) } diff --git a/DXFeedFramework/Api/DXEndpointState.swift b/DXFeedFramework/Api/DXEndpointState.swift index 0902f1001..9326c9403 100644 --- a/DXFeedFramework/Api/DXEndpointState.swift +++ b/DXFeedFramework/Api/DXEndpointState.swift @@ -7,9 +7,15 @@ import Foundation +/// A list of endpoint states. public enum DXEndpointState { + /// Endpoint was created by is not connected to remote endpoints. case notConnected + /// The ``DXEndpoint/connect(_:)`` method was called to establish connection to remove endpoint, + /// but connection is not actually established yet or was lost. case connecting + /// The connection to remote endpoint is established. case connected + /// Endpoint was ``DXEndpoint/close()`` case closed } diff --git a/DXFeedFramework/Api/DXEventListener.swift b/DXFeedFramework/Api/DXEventListener.swift index cd1beda7a..5ec926d3e 100644 --- a/DXFeedFramework/Api/DXEventListener.swift +++ b/DXFeedFramework/Api/DXEventListener.swift @@ -6,7 +6,12 @@ // import Foundation - +/// The listener delegate for receiving events. +/// public protocol DXEventListener: AnyObject { + /// Invoked when events of type are received. + /// + /// - Parameters: + /// - events: The collection of received events. func receiveEvents(_ events: [MarketEvent]) } diff --git a/DXFeedFramework/Api/DXFeedSubcription.swift b/DXFeedFramework/Api/DXFeedSubcription.swift index c488a9b80..d2322055f 100644 --- a/DXFeedFramework/Api/DXFeedSubcription.swift +++ b/DXFeedFramework/Api/DXFeedSubcription.swift @@ -7,9 +7,16 @@ import Foundation +/// Subscription for a set of symbols and event types. +/// +/// [Read it first Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html) public class DXFeedSubcription { + /// Subscription native wrapper. private let native: NativeSubscription + /// List of event types associated with this ``DXFeedSubscription`` fileprivate let events: Set + /// A set listeners of events + /// observers - typed list wrapper. private let listeners = ConcurrentSet() internal init(native: NativeSubscription?, events: [EventCode]) throws { @@ -20,7 +27,14 @@ public class DXFeedSubcription { } self.events = Set(events) } - + /// Adds listener for events. + /// Event lister can be added only when subscription is not producing any events. + /// The subscription must be either empty (no symbols have been added) + /// or not attached to any feed. + /// This method does nothing if this subscription is closed. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html#addEventListener-com.dxfeed.api.DXFeedEventListener) + /// - Throws: GraalException. Rethrows exception from Java. public func add(observer: O) throws where O: DXEventListener, O: Hashable { @@ -31,20 +45,51 @@ public class DXFeedSubcription { } listeners.insert(observer) } - + /// Removes listener for events. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html#addEventListener-com.dxfeed.api.DXFeedEventListener-) public func remove(observer: O) where O: DXEventListener, O: Hashable { listeners.remove(observer) } + /// Adds the specified symbol to the set of subscribed symbols. + /// + /// All registered event listeners will receive update on the last events for + /// newly added symbol. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html#addSymbols-java.util.Collection-) + /// - Parameters: + /// - symbol: One symbol + /// - Throws: GraalException. Rethrows exception from Java. public func addSymbols(_ symbol: Symbol) throws { try native.addSymbols(symbol) } + /// Adds the specified collection of symbols to the set of subscribed symbols. + /// + /// All registered event listeners will receive update on the last events for all + /// newly added symbols. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html#addSymbols-java.util.Collection-) + /// - Parameters: + /// - symbol: The collection of symbols. + /// - Throws: GraalException. Rethrows exception from Java. public func addSymbols(_ symbols: [Symbol]) throws { try native.addSymbols(symbols) } + + /// Removes the specified collection of symbols from the set of subscribed symbols. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXFeedSubscription.html#removeSymbols-java.util.Collection-) + /// - Parameters: + /// - symbol: The collection of symbols. + /// - Throws: GraalException. Rethrows exception from Java. + public func removeSymbols(_ symbols: [Symbol]) throws { + try native.removeSymbols(symbols) + } + } extension DXFeedSubcription: DXEventListener { diff --git a/DXFeedFramework/Api/DXPublisher.swift b/DXFeedFramework/Api/DXPublisher.swift index 9c0adc840..0fc0aa266 100644 --- a/DXFeedFramework/Api/DXPublisher.swift +++ b/DXFeedFramework/Api/DXPublisher.swift @@ -7,6 +7,9 @@ import Foundation +/// Provides API for publishing of events to local or remote ``DXFeed`` +/// +/// [Read it first Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/DXPublisher.html) public class DXPublisher { #warning("TODO: implement it") diff --git a/DXFeedFramework/Api/Osub/IObservableSubscription.swift b/DXFeedFramework/Api/Osub/IObservableSubscription.swift index da52de5f2..102a3f9e8 100644 --- a/DXFeedFramework/Api/Osub/IObservableSubscription.swift +++ b/DXFeedFramework/Api/Osub/IObservableSubscription.swift @@ -7,8 +7,24 @@ import Foundation +/// Observable set of subscription symbols for the specific event type. +/// +/// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/ObservableSubscription.html) public protocol IObservableSubscription { + /// Gets a value indicating whether if this subscription is closed. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/ObservableSubscription.html#isClosed--) func isClosed() -> Bool + /// Gets a set of subscribed event types. The resulting set cannot be modified. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/ObservableSubscription.html#getEventTypes--) + /// - Returns: a set of subscribed event types. var eventTypes: Set { get } + /// Gets a value indicating whether if this subscription contains the corresponding event type. + /// + /// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/ObservableSubscription.html#containsEventType-java.lang.Class-) + /// - Parameters: + /// - eventType: The event type. + /// - Returns: **true** if this subscription contains the corresponding event type func isContains(_ eventType: EventCode) -> Bool } diff --git a/DXFeedFramework/Api/Osub/IndexedEventSubscriptionSymbol.swift b/DXFeedFramework/Api/Osub/IndexedEventSubscriptionSymbol.swift index b53593079..6fcd25bc1 100644 --- a/DXFeedFramework/Api/Osub/IndexedEventSubscriptionSymbol.swift +++ b/DXFeedFramework/Api/Osub/IndexedEventSubscriptionSymbol.swift @@ -7,15 +7,34 @@ import Foundation +/// Represents subscription to a specific source of indexed events. +/// +/// Instances of this class can be used with ``DXFeedSubcription`` +/// to specify subscription to a particular source of indexed events. +/// By default, when subscribing to indexed events by their event symbol object, +/// the subscription is performed to all supported sources. +/// +/// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/IndexedEventSubscriptionSymbol.html) +/// +/// `T`: The type of event symbol public class IndexedEventSubscriptionSymbol: Symbol { + /// Gets event symbol. let symbol: T + /// Gets indexed event source. ``IndexedEventSource`` let source: IndexedEventSource - init(symbol: T, source: IndexedEventSource) { + /// Initializes a new instance of the ``IndexedEventSubscriptionSymbol`` class + /// with a specified event symbol and source. + /// + /// - Parameters: + /// - symbol: The event symbol. + /// - source: The event source. + public init(symbol: T, source: IndexedEventSource) { self.symbol = symbol self.source = source } - func toString() -> String { + /// Custom symbol has to return string representation. + public var stringValue: String { return "\(symbol)source=\(source.toString())" } } diff --git a/DXFeedFramework/Api/Osub/String+Symbol.swift b/DXFeedFramework/Api/Osub/String+Symbol.swift index 7a80d44ad..950adc3e2 100644 --- a/DXFeedFramework/Api/Osub/String+Symbol.swift +++ b/DXFeedFramework/Api/Osub/String+Symbol.swift @@ -7,6 +7,7 @@ import Foundation +/// String extends Symbol protocol for using inside ``DXFeedSubcription`` extension String: Symbol { public var stringValue: String { return description diff --git a/DXFeedFramework/Api/Osub/Symbol.swift b/DXFeedFramework/Api/Osub/Symbol.swift index ed7dc6d38..dfee4dd6b 100644 --- a/DXFeedFramework/Api/Osub/Symbol.swift +++ b/DXFeedFramework/Api/Osub/Symbol.swift @@ -7,7 +7,12 @@ import Foundation +/// Protocol for implement your custom symbol +/// +/// Dervied from this procol can be used with ``DXFeedSubcription`` to specify subscription + public protocol Symbol { + /// Custom symbol has to return string representation. var stringValue: String { get } } diff --git a/DXFeedFramework/Api/Osub/TimeSeriesSubscriptionSymbol.swift b/DXFeedFramework/Api/Osub/TimeSeriesSubscriptionSymbol.swift index ae38e547a..3438b3a3f 100644 --- a/DXFeedFramework/Api/Osub/TimeSeriesSubscriptionSymbol.swift +++ b/DXFeedFramework/Api/Osub/TimeSeriesSubscriptionSymbol.swift @@ -6,14 +6,33 @@ // import Foundation - +/// Represents subscription to time-series of events. +/// +/// Instances of this class can be used with ``DXFeedSubcription`` to specify subscription +/// for time series events from a specific time. By default, subscribing to time-series events by +/// their event symbol object, the subscription is performed to a stream of new events as they happen only. +/// +/// [Javadoc](https://docs.dxfeed.com/dxfeed/api/com/dxfeed/api/osub/TimeSeriesSubscriptionSymbol.html) +/// +/// `T`: The type of event symbol. public class TimeSeriesSubscriptionSymbol: IndexedEventSubscriptionSymbol { let fromTime: Long + /// Initializes a new instance of the ``TimeSeriesSubscriptionSymbol`` class + /// with a specified event symbol and from time in milliseconds since Unix epoch. + /// + /// - Parameters: + /// - symbol: The event symbol. + /// - fromTime: The from time is measured in milliseconds between the current time and midnight, January 1, 1970 UTC. public init(symbol: AnyHashable, fromTime: Long) { self.fromTime = fromTime super.init(symbol: symbol, source: IndexedEventSource.defaultSource) } - + /// Initializes a new instance of the ``TimeSeriesSubscriptionSymbol`` class + /// with a specified event symbol and from date + /// + /// - Parameters: + /// - symbol: The event symbol. + /// - date: Date. Just for easing initialization with date object convenience public init(symbol: AnyHashable, date: Date) { self.init(symbol: symbol, fromTime: Long(date.timeIntervalSince1970) * 1000) } @@ -22,7 +41,8 @@ public class TimeSeriesSubscriptionSymbol: IndexedEventSubscriptionSymbol Bool { let thread = currentThread() let success = try? ErrorCheck.nativeCall(thread, dxfg_DXFeedSubscription_isClosed(thread, self.subscription))