Merge pull request #2 from LukasPoque/add_policy_feature

Add policy feature

Author: LukasPoque

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.0
+
+Add Policy classes.
+- add policies: `PolicyEntry` as class for all policies in the directory or repository, using `PolicyGroup`, `PolicyResource`, `PolicySubject` for
+a better data encapsulation
+- add `InvalidArgumentException` for arguments which are not matching the expectations
+
 ## 0.1.0
 
 First release of the S3I Flutter package. Currently supported:

README.md

@@ -27,6 +27,13 @@
 </p>
 
 
+## About S³I and KWH4.0
+
+If you are not familiar with the S³I concepts, please read the 
+[KWH4.0-Standpunkt](https://www.kwh40.de/wp-content/uploads/2020/04/KWH40-Standpunkt-S3I-v2.0.pdf).
+
+For further information see the [KWH Glossar](https://www.kwh40.de/glossar/) and the other [Standpunkte](https://www.kwh40.de/veroffentlichungen/).
+
 ## Installing
 
 Add it to your `pubspec.yaml` file:
@@ -42,20 +49,13 @@ flutter packages get
 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:
 
-## About S³I and KWH4.0
-
-If you are not familiar with the S³I concepts, please consider reading the 
-[KWH4.0-Standpunkt](https://www.kwh40.de/wp-content/uploads/2020/04/KWH40-Standpunkt-S3I-v2.0.pdf).
-
-For further information see the [KWH Glossar](https://www.kwh40.de/glossar/) and the other [Standpunkte](https://www.kwh40.de/veroffentlichungen/).
-
 ## Usage
 
 For a basic example application see the [example](https://github.com/LukasPoque/s3i_flutter/tree/master/example).
 
-### Setup Auth
+### Setup authentication
 
-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.
 ```dart
 final clientIdentity = ClientIdentity(<CLIENT-ID>, <CLIENT-SECRET>);
 ```
@@ -70,7 +70,7 @@ final authManager = OAuthProxyFlow(clientIdentity,
       scopes: ["group", "offline_access"]);
 ```
 
-Last but not least you should use this `AuthenticationManager`-Instance to create a `S3ICore`-Instance. Now you could work with the `S3I`.
+Last but not least you should use this `AuthenticationManager`-Instance to create a `S3ICore`-Instance.
 ```dart
 final s3i = S3ICore(authManager);
 ```
@@ -85,9 +85,11 @@ try {
 }
 ````
 
-### Send Requests to the directory
+If the `S3ICore`-Instance is ready to use you can now receive and update information from the S3I-Services. 
 
-If the `S3ICore`-Instance is ready to use you can receive information about a specific thing by calling `getThing()`. 
+### 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 
 which is faster and safes network data.
 ```dart
@@ -98,6 +100,36 @@ try {
 }
 ```
 
+Similar to this you can request a specific policy from the directory:
+```dart
+try {
+  var policy = await s3i.getPolicy(<POLICY_ID>));
+} on S3IException catch (e) {
+  debugPrint("Request Policy failed: " + e.toString());
+}
+```
+
+TODO: add search example
+
+### 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 to unintentionally overwriting much more likely.
+
+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"));
+try {
+  await s3i.putPolicy(policyEntry);
+} on S3IException catch (e) {
+  debugPrint("Update Policy failed: " + e.toString());
+}
+```
+
+### Send and receive messages via S3I-Broker
+
+TODO: ...
 
 ## Project Structure
 
@@ -116,6 +148,16 @@ But it doesn't refreshes the tokens automatically, only only if `getAccessToken`
 
 ### policy
 
+The `policy` folder includes data classes to store and manipulate the policy entries of a thing from the directory OR repository.
+
+A `PolicyEntry` consists of `PolicyGroup`s and manages the access control to one specific `Entry`.
+Each one has it's own policy entry which is only valid for the the service where it's stored (directory/repository).
+For more background information see: https://www.eclipse.org/ditto/basic-policy.html
+
+In the S3I-Concept there are two special `PolicyGroup`s which have a specific meaning:
+- 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
 
 ### exceptions

example/lib/main.dart

@@ -51,10 +51,12 @@ class MyHomePage extends StatefulWidget {
 
 class _MyHomePageState extends State<MyHomePage> {
   final thingIdInputController = TextEditingController();
+  final policyIdInputController = TextEditingController();
 
   // s3i values
   AccessToken? accessToken;
   Thing? requestedThing;
+  PolicyEntry? requestedPolicy;
 
   @override
   Widget build(BuildContext context) {
@@ -70,7 +72,9 @@ class _MyHomePageState extends State<MyHomePage> {
               Divider(height: 5, thickness: 5),
               _buildThingRequestArea(),
               Divider(height: 5, thickness: 5),
-              _buildEditThingArea()
+              _buildEditThingArea(),
+              Divider(height: 5, thickness: 5),
+              _buildPolicyRequestArea()
             ],
           ),
         ));
@@ -135,9 +139,12 @@ class _MyHomePageState extends State<MyHomePage> {
                     } on S3IException catch (e) {
                       debugPrint("Request Thing failed");
                       debugPrint(e.toString());
+                      setState(() {
+                        requestedThing = null;
+                      });
                     }
                   },
-                  child: Text("Request"))
+                  child: Text("Request Thing"))
             ],
           ),
           SizedBox(height: 8),
@@ -172,6 +179,47 @@ class _MyHomePageState extends State<MyHomePage> {
         : Container();
   }
 
+  Widget _buildPolicyRequestArea() {
+    return Padding(
+      padding: const EdgeInsets.all(16.0),
+      child: Column(
+        children: [
+          Row(
+            children: [
+              Expanded(
+                child: TextField(
+                  controller: policyIdInputController,
+                ),
+              ),
+              SizedBox(width: 8),
+              OutlinedButton(
+                  onPressed: () async {
+                    try {
+                      // requests the given policy
+                      // you need read access to the policy
+                      var policy = await MyHomePage.s3i
+                          .getPolicy(policyIdInputController.text);
+                      setState(() {
+                        requestedPolicy = policy;
+                      });
+                    } on S3IException catch (e) {
+                      debugPrint("Request Policy failed");
+                      debugPrint(e.toString());
+                      setState(() {
+                        requestedPolicy = null;
+                      });
+                    }
+                  },
+                  child: Text("Request Policy"))
+            ],
+          ),
+          SizedBox(height: 8),
+          if (requestedPolicy != null) Text(requestedPolicy.toString())
+        ],
+      ),
+    );
+  }
+
   @override
   void dispose() {
     thingIdInputController.dispose();

example/pubspec.lock

@@ -134,7 +134,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.0.1"
+    version: "0.2.0"
   sky_engine:
     dependency: transitive
     description: flutter

lib/s3i_flutter.dart

@@ -18,6 +18,12 @@ export 'src/exceptions/parse_exception.dart';
 export 'src/exceptions/max_retry_exception.dart';
 export 'src/exceptions/network_response_exception.dart';
 
+//policy
+export 'src/policy/policy_entry.dart';
+export 'src/policy/policy_group.dart';
+export 'src/policy/policy_resource.dart';
+export 'src/policy/policy_subject.dart';
+
 //query
 export 'src/query/query_assembler.dart';
 export 'src/query/field_query.dart';

lib/src/exceptions/invalid_argument_exception.dart

@@ -0,0 +1,11 @@
+import 'package:s3i_flutter/src/exceptions/s3i_exception.dart';
+
+/// Exception thrown when an argument is not matching the expectations.
+class InvalidArgumentException extends S3IException {
+  InvalidArgumentException(String message) : super(message);
+
+  @override
+  String toString() {
+    return "InvalidArgumentException: $errorMessage";
+  }
+}