JDS protocol | refactored, added documentation

lib/hmi_networking.dart

@@ -10,19 +10,13 @@ export 'src/core/ds_client/cache/file/ds_cache_file.dart';
 export 'src/core/ds_client/cache/file/ds_client_file_cache.dart';
 export 'src/core/ds_client/cache/memory/ds_client_memory_cache.dart';
 export 'src/core/ds_client/cache/update_cache_from_point_configs.dart';
-export 'src/core/request_destination.dart';
-export 'src/core/socket_destination.dart';
-export 'src/protocols/jds_service/jds_service.dart';
-export 'src/protocols/jds_service/jds_service_destination.dart';
-export 'src/protocols/jds_service/jds_service_startup.dart';
-export 'src/protocols/jds_service/jds_package/jds_package.dart';
-export 'src/protocols/jds_service/jds_package/jds_cot.dart';
-export 'src/protocols/jds_service/jds_package/jds_data_type.dart';
-export 'src/protocols/jds_service/jds_point_config/jds_point_config.dart';
-export 'src/protocols/jds_service/jds_point_config/jds_point_configs.dart';
-export 'src/protocols/jds_service/jds_point_config/ds_access_mode.dart';
-export 'src/protocols/jds_service/jds_point_config/ds_filters.dart';
-export 'src/protocols/jds_service/jds_point_config/ds_point_address.dart';
+export 'src/core/jds_service/jds_service.dart';
+export 'src/core/jds_service/jds_service_startup.dart';
+export 'src/core/jds_service/jds_point_config/jds_point_config.dart';
+export 'src/core/jds_service/jds_point_config/jds_point_configs.dart';
+export 'src/core/jds_service/jds_point_config/ds_access_mode.dart';
+export 'src/core/jds_service/jds_point_config/ds_filters.dart';
+export 'src/core/jds_service/jds_point_config/ds_point_address.dart';
 export 'src/core/line_socket/ds_line_socket.dart';
 export 'src/core/line_socket/line_socket.dart';
 export 'src/core/ds_data_stream_extract.dart';
@@ -33,8 +27,18 @@ export 'src/core/entities/network_operation_state.dart';
 export 'src/core/entities/data_object.dart';
 export 'src/core/entities/response.dart';
 export 'src/core/entities/internet_endpoint.dart';
+export 'src/protocols/protocol_endpoint.dart';
+export 'src/protocols/transport_endpoint.dart';
+export 'src/protocols/transport_connection.dart';
+export 'src/protocols/transport_protocol.dart';
 export 'src/protocols/custom_protocol_line.dart';
 export 'src/protocols/jsd_line.dart';
+export 'src/protocols/jds/jds_endpoint.dart';
+export 'src/protocols/jds/jds_package/jds_package.dart';
+export 'src/protocols/jds/jds_package/jds_cot.dart';
+export 'src/protocols/jds/jds_package/jds_data_type.dart';
+export 'src/protocols/tcp/tcp.dart';
+export 'src/protocols/tcp/tcp_connection.dart';
 export 'src/api/api_handle_error.dart';
 export 'src/api/api_params.dart';
 export 'src/api/api_request.dart';

lib/src/core/ds_client/cache/update_cache_from_point_configs.dart

@@ -1,19 +1,27 @@
 import 'package:hmi_core/hmi_core.dart';
 import 'package:hmi_core/hmi_core_result_new.dart';
 import 'package:hmi_networking/src/core/ds_client/cache/ds_client_cache.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_service.dart';
-///
+import 'package:hmi_networking/src/core/jds_service/jds_service.dart';
+/// 
+/// [JdsService] cache update sequence.
 class UpdatePointsCacheFromJdsService {
   final DsClientCache _cache;
   final JdsService _jdsService;
   ///
+  /// [JdsService] cache update sequence.
+  /// 
+  /// [jdsService] - to pull config from.
+  /// 
+  /// [cache] - to save config to.
   const UpdatePointsCacheFromJdsService({
     required DsClientCache cache, 
     required JdsService jdsService,
   }) : 
     _cache = cache, 
     _jdsService = jdsService;
   ///
+  /// Pull points config fron JDS service and 
+  /// save default values of new poins if any appeared.
   Future<ResultF<void>> apply() async {
     final cachePointNames = (await _cache.getAll())
       .map((point) => point.name.toString()).toSet();

lib/src/core/ds_client/ds_client_real.dart

@@ -5,7 +5,7 @@ import 'package:hmi_networking/src/core/ds_client/cache/ds_client_cache.dart';
 import 'package:hmi_networking/src/core/ds_client/cache/update_cache_from_point_configs.dart';
 import 'package:hmi_networking/src/core/ds_client/ds_client.dart';
 import 'package:hmi_networking/src/core/ds_client/ds_client_connection_listener.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_service.dart';
+import 'package:hmi_networking/src/core/jds_service/jds_service.dart';
 import 'package:hmi_networking/src/protocols/custom_protocol_line.dart';
 
 ///

lib/src/protocols/jds_service/jds_point_config/ds_filters.dart → lib/src/core/jds_service/jds_point_config/ds_filters.dart

@@ -1,3 +1,4 @@
+///
 class DsFilters {
   final double? threshold;
   final double? factor;

lib/src/protocols/jds_service/jds_point_config/jds_point_config.dart → lib/src/core/jds_service/jds_point_config/jds_point_config.dart

@@ -1,7 +1,8 @@
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_data_type.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_point_config/ds_access_mode.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_point_config/ds_filters.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_point_config/ds_point_address.dart';
+import 'package:hmi_networking/src/protocols/jds/jds_package/jds_data_type.dart';
+import 'package:hmi_networking/src/core/jds_service/jds_point_config/ds_access_mode.dart';
+import 'package:hmi_networking/src/core/jds_service/jds_point_config/ds_filters.dart';
+import 'package:hmi_networking/src/core/jds_service/jds_point_config/ds_point_address.dart';
+
 ///
 class JdsPointConfig {
   final JdsDataType type;

lib/src/protocols/jds_service/jds_service.dart → lib/src/core/jds_service/jds_service.dart

@@ -1,27 +1,29 @@
 import 'package:hmi_core/hmi_core.dart';
 import 'package:hmi_core/hmi_core_result_new.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_cot.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_data_type.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_package.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_point_config/jds_point_configs.dart';
-import 'package:hmi_networking/src/core/request_destination.dart';
+import 'package:hmi_networking/hmi_networking.dart';
+
 ///
+/// Collection of JDS requests supported by service on external server.
 class JdsService {
-  final RequestDestination<JdsPackage, JdsPackage> _jdsDestination;
+  final JdsEndpoint _endpoint;
   ///
+  /// Collection of JDS requests supported by service on external server.
+  /// 
+  /// [endpoint] - to communicate through JDS protocol.
   const JdsService({
-    required RequestDestination<JdsPackage, JdsPackage> jdsDestination,
+    required JdsEndpoint endpoint,
   }) : 
-    _jdsDestination = jdsDestination;
+    _endpoint = endpoint;
   ///
+  /// Proceed to authentication process with [token].
   Future<ResultF<void>> authenticate(String token) {
-    return _jdsDestination.send(
-      JdsPackage(
-        type: JdsDataType.string, 
-        value: token, 
-        name: DsPointName('/App/Jds/Authenticate'), 
-        status: DsStatus.ok, 
-        cot: JdsCot.req, 
+    return _endpoint.exchange(
+      JdsPackage<String>(
+        type: JdsDataType.string,
+        value: token,
+        name: DsPointName('/App/Jds/Authenticate'),
+        status: DsStatus.ok,
+        cot: JdsCot.req,
         timestamp: DateTime.now(),
       ),
     ).then((result) => switch(result) {
@@ -30,14 +32,15 @@ class JdsService {
     });
   }
   ///
+  /// Get configuration of data points from the server.
   Future<ResultF<JdsPointConfigs>> points() {
-    return _jdsDestination.send(
+    return _endpoint.exchange(
       JdsPackage<String>(
-        type: JdsDataType.string, 
-        value: '', 
-        name: DsPointName('/App/Jds/Points'), 
-        status: DsStatus.ok, 
-        cot: JdsCot.req, 
+        type: JdsDataType.string,
+        value: '',
+        name: DsPointName('/App/Jds/Points'),
+        status: DsStatus.ok,
+        cot: JdsCot.req,
         timestamp: DateTime.now(),
       ),
     )
@@ -59,14 +62,15 @@ class JdsService {
     });
   }
   ///
+  /// Tell server to send specific data points.
   Future<ResultF<void>> subscribe([List<String> names = const []]) {
-    return _jdsDestination.send(
+    return _endpoint.exchange(
       JdsPackage<String>(
-        type: JdsDataType.string, 
-        value: '[${names.join(',')}]', 
-        name: DsPointName('/App/Jds/Subscribe'), 
-        status: DsStatus.ok, 
-        cot: JdsCot.req, 
+        type: JdsDataType.string,
+        value: '[${names.join(',')}]',
+        name: DsPointName('/App/Jds/Subscribe'),
+        status: DsStatus.ok,
+        cot: JdsCot.req,
         timestamp: DateTime.now(),
       ),
     ).then((result) => switch(result) {

lib/src/protocols/jds_service/jds_service_startup.dart → lib/src/core/jds_service/jds_service_startup.dart

@@ -1,19 +1,27 @@
 import 'package:hmi_core/hmi_core_result_new.dart';
 import 'package:hmi_networking/src/core/ds_client/cache/ds_client_cache.dart';
 import 'package:hmi_networking/src/core/ds_client/cache/update_cache_from_point_configs.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_service.dart';
-///
+import 'package:hmi_networking/src/core/jds_service/jds_service.dart';
+
+/// 
+/// [JdsService] startup sequence.
 class JdsServiceStartup {
   final JdsService _service;
   final DsClientCache? _cache;
   ///
+  /// [JdsService] startup sequence.
+  /// 
+  /// If [cache] is provided, config from server will be saved to it.
   const JdsServiceStartup({
     required JdsService service,
     DsClientCache? cache,
   }) : 
     _service = service,
     _cache = cache;
   ///
+  /// Pull points config from JDS service,
+  /// save it to cache (if provided) 
+  /// and subscribe for all of the points.
   Future<ResultF<void>> run() async {
     // await _service.authenticate('');
     final configResult = await _service.points();

lib/src/protocols/jds_service/jds_service_destination.dart → lib/src/protocols/jds/jds_endpoint.dart

@@ -1,25 +1,31 @@
 import 'dart:convert';
 import 'package:hmi_core/hmi_core.dart';
 import 'package:hmi_core/hmi_core_result_new.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_package.dart';
-import 'package:hmi_networking/src/core/request_destination.dart';
-///
-class JdsServiceDestination implements RequestDestination<JdsPackage, JdsPackage> {
-  final RequestDestination<List<int>, List<int>> _bytesDestination;
-  ///
-  const JdsServiceDestination({
-    required RequestDestination<List<int>, List<int>> bytesDestination,
-  }) : _bytesDestination = bytesDestination;
+import 'package:hmi_networking/src/protocols/transport_endpoint.dart';
+import 'package:hmi_networking/src/protocols/jds/jds_package/jds_package.dart';
+import 'package:hmi_networking/src/protocols/protocol_endpoint.dart';
+
+/// 
+/// Destination supporting JDS communication protocol.
+class JdsEndpoint implements ProtocolEndpoint<JdsPackage, JdsPackage> {
+  final TransportEndpoint _tansportEndpoint;
   ///
+  /// Destination supporting JDS communication protocol.
+  /// 
+  /// [transportEndpoint] - binary destination to transfer serialized JDS packages over it.
+  const JdsEndpoint({
+    required TransportEndpoint transportEndpoint,
+  }) : _tansportEndpoint = transportEndpoint;
+  //
   @override
-  Future<ResultF<JdsPackage>> send(JdsPackage package) async {
+  Future<ResultF<JdsPackage>> exchange(JdsPackage package) async {
     return switch(_encodeJson(package)) {      
-      Ok(value: final bytes) => _decodeResult(await _bytesDestination.send(bytes)),
+      Ok(value: final bytes) => _decodeResult(await _tansportEndpoint.exchange(bytes)),
       Err(:final error) => Err(error),
     };
   }
   ///
-  ResultF<JdsPackage> _decodeResult(ResultF<List<int>> bytesResult) => switch(bytesResult){
+  ResultF<JdsPackage> _decodeResult(ResultF<List<int>> bytesResult) => switch(bytesResult) {
     Ok(value:final bytes) => _decodeJson(bytes),
     Err(:final error) => Err(error),
   };

lib/src/protocols/jds_service/jds_package/jds_cot.dart → lib/src/protocols/jds/jds_package/jds_cot.dart

@@ -1,13 +1,29 @@
-/// Json data storage - Cause of transmission
+///
+/// Cause of transmission of JDS package
 enum JdsCot {
+  /// 
+  /// Information
   inf,
+  /// 
+  /// Command
   act,
+  /// 
+  /// Command completed
   actCon,
+  /// 
+  /// Command failed
   actErr,
+  /// 
+  /// Request
   req,
+  /// 
+  /// Request completed
   reqCon,
+  /// 
+  /// Request failed
   reqErr;
   ///
+  /// Cause of transmission of JDS package
   const JdsCot();
   ///
   factory JdsCot.fromString(String cot) {

lib/src/protocols/jds_service/jds_package/jds_package.dart → lib/src/protocols/jds/jds_package/jds_package.dart

@@ -1,7 +1,7 @@
 import 'package:hmi_core/hmi_core.dart';
 import 'package:hmi_core/hmi_core_result_new.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_cot.dart';
-import 'package:hmi_networking/src/protocols/jds_service/jds_package/jds_data_type.dart';
+import 'package:hmi_networking/src/protocols/jds/jds_package/jds_cot.dart';
+import 'package:hmi_networking/src/protocols/jds/jds_package/jds_data_type.dart';
 ///
 class JdsPackage<T> {
   final JdsDataType type;

lib/src/protocols/protocol_endpoint.dart

@@ -0,0 +1,8 @@
+import 'package:hmi_core/hmi_core_result_new.dart';
+/// 
+/// Destination to send [I] entity and receive an answer as [O] through some protocol.
+abstract interface class ProtocolEndpoint<I,O> {
+  /// 
+  /// Send [data] and receive desired answer according to protocol.
+  Future<ResultF<O>> exchange(I data);
+}