Merge pull request #5 from LukasPoque/add_broker_feature

Add broker feature

Author: LukasPoque

CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.4.0
+
+Add S3I-Broker functionality:
+- S3I-B-Messages classes (Message, UserMessage, ServiceMessage (ServiceRequest, ServiceReply), AttributeValueMessage (GetValueRequest, GetValueReply))
+- Basic interfaces for the Broker communication (BrokerInterface, ActiveBrokerInterface, PassiveBrokerInterface):
+  - ActiveBrokerInterface for interfaces that inform you whenever a new message is available
+  - PassiveBrokerInterface for interfaces where you need to explicitly ask if there are new messages
+- An implementation of the ActiveBrokerInterface using the AMQP protocol (not usable for web)
+- An implementation of the ActiveBrokerInterface using the REST API of the broker
+
 ## 0.3.0
 
 Add linting rules and fulfill them.

README.md

@@ -36,9 +36,13 @@ If you are not familiar with the S³I concepts, please read the
 
 For further information see the [KWH Glossar](https://www.kwh40.de/glossar/) and the other [Standpunkte](https://www.kwh40.de/veroffentlichungen/).
 
+## Contributing
+
+PRs are always welcome, check [CONTRIBUTING.md](https://github.com/LukasPoque/s3i_flutter/blob/master/CONTRIBUTING.md) for more info.
+
 ## Installing
 
-Please see [Pub.dev](https://pub.dev/packages/s3i_flutter/install) for instructions how to install this package to your flutter app. 
+Please see [pub.dev](https://pub.dev/packages/s3i_flutter/install) for instructions how to install this package to your flutter app. 
 
 If you like this package, consider supporting it by giving a star on [GitHub](https://github.com/LukasPoque/s3i_flutter) and 
 a like on [pub.dev](https://pub.dev/packages/s3i_flutter) :heart:
@@ -47,15 +51,20 @@ a like on [pub.dev](https://pub.dev/packages/s3i_flutter) :heart:
 
 For a basic example application see the [example](https://github.com/LukasPoque/s3i_flutter/tree/master/example).
 
+Use the [documentation](https://pub.dev/documentation/s3i_flutter/latest/s3i_flutter/s3i_flutter-library.html) of this package for 
+explicit information about every public method or class.
+
 ### Setup authentication
 
-First you need to create a `ClientIdentity` used by your app. Please contact the [KWH4.0](https://www.kwh40.de/kontakt/) to get an app specific client.
+First you need to create a `ClientIdentity` used by your app. Please contact the [KWH4.0](https://www.kwh40.de/kontakt/) to get an app 
+specific client. If you need special client settings like redirect urls (e.g. for the use of the S3I-OAuthProxy) please include this in your
+request.
 ```dart
 final clientIdentity = ClientIdentity(<CLIENT-ID>, <CLIENT-SECRET>);
 ```
 
 Now you can pass this to an `AuthenticationManager` of your choice. 
-See [here](https://github.com/LukasPoque/s3i_flutter#auth) for a list of some implementations.
+See [here](https://github.com/LukasPoque/s3i_flutter#Auth) for a list of some implementations.
 In this example we use the `OAuthProxyFlow`. You can specify some scopes to add specific claims in your token.
 ```dart
 final authManager = OAuthProxyFlow(clientIdentity,
@@ -64,24 +73,27 @@ final authManager = OAuthProxyFlow(clientIdentity,
       scopes: ["group", "offline_access"]);
 ```
 
-Last but not least you should use this `AuthenticationManager`-Instance to create a `S3ICore`-Instance.
-```dart
-final s3i = S3ICore(authManager);
-```
-
 If you want to assure that the user is authenticated before going on with other requests 
-you could trigger the auth process explicit by calling the `login()` function:
+you could trigger the auth process explicit by calling the `getAccessToken()` function:
 ````dart
 try {
-  await s3i.login();
+  await authManager.getAccessToken();
 } on S3IException catch (e) {
  debugPrint("Auth failed: " + e.toString());
 }
 ````
 
-If the `S3ICore`-Instance is ready to use you can now receive and update information from the S3I-Services. 
+### Use the S3I-Directory
+
+If you want to access the S3I-Directory, use the previous constructed `AuthenticationManager`-Instance to create a `S3ICore`-Instance.
+```dart
+final s3i = S3ICore(authManager);
+```
 
-### Get data from the directory
+If the `S3ICore`-Instance is ready to use you can now receive and update information from the S3I-Directory (This is subject of
+a change in the next releases pls. consider this in your structure). 
+
+#### Get data from the directory
 
 To get data about a specific thing you can simply call `getThing()` on your `S3ICore`-Instance. 
 If you don't need the whole thing it's recommended to use a `FieldQuery` so you only receive a part of the entry 
@@ -105,43 +117,137 @@ try {
 
 TODO: add search example
 
-### Update data in the directory
+#### Update data in the directory
 
 To update data in the directory it's recommended to request the target before changing it. 
 This is not needed, because all data classes cloud be created without a version from the cloud but since this package doesn't support `PATCH` requests,
 using only local data could lead  much more likely to unintentionally overwriting of values.
 
 To update an entry in the directory simply use the `putThing()` or `putPolicy()` method with the locally modified object:
 ```dart
-policyEntry.insertObserver(PolicySubject("nginx:test_observer"));
+policyEntry.insertObserver(PolicySubject("nginx:new_test_observer"));
 try {
   await s3i.putPolicy(policyEntry);
 } on S3IException catch (e) {
   debugPrint("Update Policy failed: " + e.toString());
 }
 ```
 
-### Send and receive messages via S3I-Broker
+### Use the S3I-Broker
 
-TODO: ...
+In order to send and receive messages via S3I-Broker you need an implementation of a `BrokerInterface`.
+See [here](https://github.com/LukasPoque/s3i_flutter#Broker) for a list of implementations and some background information.
+In this example we use an `ActiveBrokerInterface`, because it notifies us if new messages are available. If you are targeting web as a platform too,
+use the `getActiveBrokerDefaultConnector` function. This function returns either an AMQPConnector (if your app is not running as web-app) or a 
+RESTConnector. You can pass the different constructor arguments via the args-map.
+```dart
+// used to determine if the app is running on the web
+import 'package:flutter/foundation.dart' show kIsWeb;
+
+static final ActiveBrokerInterface brokerConnector = kIsWeb
+      ? getActiveBrokerDefaultConnector(authManager,
+          args: {'pollingInterval': const Duration(milliseconds: 500)})
+      : getActiveBrokerDefaultConnector(authManager);
+```
+
+Now you can register for different events of the brokerConnector. You can even register multiple times for the same event. This is useful
+if you want to use the information at different locations in the app (e.g. logging, ui, etc.).
+```dart
+brokerConnector
+    ..subscribeConsumingFailed((String endpoint, Exception error) {
+      print('Error on connection $endpoint: $error');
+    })
+    ..subscribeSendMessageFailed((Message msg, Exception error) {
+      print('Error while sending message (${msg.identifier}) $error');
+    })
+    ..subscribeSendMessageSucceeded((Message msg) {
+      print('Message with id ${msg.identifier} sent');
+    })
+```
+
+#### Receive messages
+
+To receive messages and working with them in your app it's a good idea to register callback for the receiving functions of the brokerConnector.
+In this example we're only interested in `ServiceReply`s:
+```dart
+brokerConnector.subscribeServiceReplyReceived((ServiceReply msg) {
+    print('Message with id ${msg.identifier} received');
+});
+```
+
+If all callback you're interested in are registered it's time to start consuming on one (or multiple) queues on the S3I-Broker. 
+For that simply call `startConsuming`. If you don't want any open connections left when your app closes, call `stopConsuming` with the same endpoint
+in your dispose method.
+```dart
+final String ownEndpoint = '<YOUR ENDPOINT ID>';
+brokerConnector.startConsuming(ownEndpoint);
+//...
+// dispose() or equivalent method
+brokerConnector.stopConsuming(ownEndpoint);
+```
+
+#### Send messages
+
+To send messages to other things you need to construct a message first. Then you can simply call `sendMessage` with the message and all receiver 
+endpoints on your broker instance. 
+```dart
+static final request = ServiceRequest(
+      receivers: <String>{'<SERVICE ID>'},
+      sender: '<YOUR CLIENT ID>',
+      replyToEndpoint: '<YOUR ENDPOINT ID>',
+      serviceType: '<FML40 SERVICE TYPE>',
+      parameters: <String, dynamic>{<NEEDED PARAMETERS MAP>});
+
+brokerConnector.sendMessage(requestMsg, <String>{'<SERVICE ENDPOINT>'});
+```
 
 ## Project Structure
 
-TODO: s3i core / entry
+The package is divided in domain specific folders.
+
+TODO: ...
 
-### directory
+### Auth
 
-### auth
+The `auth` folder includes classes which are used to authenticate an user/client in the S3I and could provide valid token to 
+the other parts of this package where they are used. The folder includes classes for `AccessToken` and `RefreshToken` too.
 
-The `auth` folder includes classes which are used to authenticate a user/client in the S3I.
+Currently only the following `AuthenticationManager` implementations are available: 
+- `OAuthProxyFlow`: This implementation uses the S3I-OAuthProxy to obtain an access and refresh token.
+  But it doesn't refreshes the tokens automatically, only only if `getAccessToken` is called and the previous token is expired.
 
-The `S3ICore` needs a valid instance of a `AuthenticationManager` to work.
+### Broker
 
-Currently there is only one implementation available: `OAuthProxyFlow`.
-This implementation of the `AuthenticationManager` uses the S3I-OAuthProxy to obtain an access and refresh token.
-But it doesn't refreshes the tokens automatically, only only if `getAccessToken` is called and the `accessToken` is expired.
+The `broker` folder includes data classes for the different messages specified in the S3I-B-Protocol and different implementations
+of the `BrokerInterface` for communication with the S3I-Broker.
 
-### policy
+There are two different approaches to receive messages from the Broker. An `ActiveBrokerInterface` is for interfaces that inform you 
+whenever a new message is available. A `PassiveBrokerInterface` is for interfaces where you need to explicitly ask if there are new 
+messages.
+
+At the moment, there are only active broker interfaces implemented:
+- `BrokerAmqpConnector`: uses the native communication protocol of the S3i-Broker: AMQP. This is not available for the *web* platform.
+- `BrokerRestConnector`: uses the S3I-Broker REST API for sending/receiving of messages.
+
+Currently the following message types are supported:
+- `UserMessage`: used for communication between two real users.
+- `ServiceMessage`: used to invoke service functions or receive service answers from S3I-Services.
+- `GetValueMessage`: used to get a specific value from an other thing.
+
+### Directory
+
+The `directory` folder includes data classes to store and manipulate the entries of a thing from the directory.
+
+The classes are following the *S3I-Directory-Data-Model* with the `Thing` class as their root followed by different chains of 
+`DirObject`, `Link` and `Value`.
+
+### Exceptions
+
+The `exceptions` folder includes all customized exceptions from this package.
+
+The base class is the `S3IException` which only wraps a normal `Exception` making it easier to catch all specific S3I exceptions.
+
+### Policy
 
 The `policy` folder includes data classes to store and manipulate the policy entries of a thing from the directory OR repository.
 
@@ -153,10 +259,16 @@ In the S3I-Concept there are two special `PolicyGroup`s which have a specific me
 - owner: An owner has READ and WRITE permission to everything (thing:/, policy:/, message:/)
 - observer: An observer has only READ permission to the thing part (thing:/)
 
-### broker
+### Query
+
+The `query` folder includes the parameters for a (query)request to the S3I-Directory/Repository and the S3I-EventSystem.
 
-### exceptions
+Currently the following parameters are used:
+- `FieldQuery`: Only the selected fields will be included in the returned json, good for faster and smaller responses.
+- `NamespaceQuery`: Limit the query to things in the given namespaces only.
+- `OptionQuery`: Used for sorting the responses or enable paging/cursor mechanisms.
+- `RQLQuery`: A lightweight query language for the use in URLs (this could be separated to an external package in the future).
 
-### query
+### Utils
 
-### utils
+The `utils` folder includes useful tools for the whole package. Currently it contains constant json-keys from the S3I-Services.