@aj-shadow/actorjs-documentation-text 0.0.0-aj-beta.221

package/Documentation/actor-api/Document-global-shared-data.txt

@@ -0,0 +1,259 @@
+# **Shared Data API**
+[[API-STATUS=STABLE, ]]
+[[DOC-STATUS=PARTLY, ]]
+
+[[NOTE={"guid":"75a52038-8f65-4c35-89d8-a21008592327"}]]
+[[ANCHOR={"id":"62ef30d3-2888-4fbd-83dc-8869a30fe4b8","visible":true}]]
+## **Description**
+
+An [[REF=, ABS_Actor]] can publish data to other [[REF=, ABS_Actor]]s through the shared Data API. It is the publishing [[REF=, ABS_Actor]] who decides the format of the [[REF=, ABS_Shared_Data]]. The implementation of the Shared Data API starts in [[REF=, CODE_Shared_Data]].
+
+
+[[NOTE={"guid":"b6970c24-e472-4a8e-8799-a426be0bf76b"}]]
+[[ANCHOR={"id":"30144890-36f8-4553-981c-0ea6b35a1776","visible":true}]]
+## **API Methods**
+* **[*setSharedData](#shared-data-api-set-shared-data)**
+* **[setSharedDataSync](#shared-data-api-set-shared-data-sync)**
+* **[getSharedData](#shared-data-api-get-shared-data)**
+* **[*waitForSharedData](#shared-data-api-wait-for-shared-data)**
+* **[*setSharedDataActor](#shared-data-api-set-shared-data-actor)**
+* **[getSharedDataActor](#shared-data-api-get-shared-data-actor)**
+* **[*waitForSharedDataActor](#shared-data-api-wait-for-shared-data-actor)**
+
+***
+
+[[NOTE={"guid":"5a217975-508e-4083-8ba4-f907f2c23904"}]]
+[[ANCHOR={"id":"shared-data-api-set-shared-data","visible":true}]]
+### ***setSharedData**
+```
+this.setSharedData(key[, value])
+```
+
+[[NOTE={"guid":"0fc9aee7-4687-47d4-9448-75020f114160"}]]
+[[ANCHOR={"id":"182cd163-fd16-4963-beeb-4bb7749386d1","visible":true}]]
+#### **Method Description**
+
+Publishes [[REF=, ABS_Shared_Data]] to be read by other [[REF=, ABS_Actor]]s.
+ If other [[REF=, ABS_Actor]]s are waiting for the ***key*** with the method [*waitForSharedData](#shared-data-api-wait-for-shared-data) they will be awaken if their awaken crefeterias are fulfilled. 
+
+```table
+Config(classHeading: )
+
+|Parameters                                                                    |
+|Name |Type               Default|         |Description                        |
+|key  |[[REF=,MDN_string]]       |         |The ***key*** of the Shared Data.  |
+|value|<**any**>           |undefined|The ***value*** of the Shared Data.|
+```
+
+```table
+Config(classHeading: )
+
+|Returns                                   |
+|Type           |Description               |
+|<**any**>|The parameter ***value***.|
+```
+
+```table
+Config(classHeading: )
+
+|Async                    |
+|type      |Description   |
+|**yield***|auto generated|
+```
+
+[[NOTE={"guid":"1380be73-3ffb-425f-b6ba-f79052723a94"}]]
+[[ANCHOR={"id":"e5b9e68e-6779-43df-9ef1-ee5199ec9cef","visible":true}]]
+#### **Example using setSharedData**
+
+```javascript
+
+*run() {
+  let myBool = true;
+  this.setSharedData('demoKey1', 'Hello');      // sets value to "Hello"
+  this.setSharedData('demoKey2', 5);            // sets value to => 5
+  this.setSharedData('demoKey3', !myBool);      // sets value to => false
+  this.setSharedData('synchronize');            // do not set any value, but awakens Actors waiting for the key "synchronize".
+}
+
+```
+
+[[NOTE={"guid":"bc7eb019-bfbf-4197-aceb-0527047f720e"}]]
+[[ANCHOR={"id":"cf285054-41ee-40df-9194-2b07f7b4ef16","visible":true}]]
+#### **Test Cases setSharedData**
++ [DocActorApiSharedDataSetGetValue](/../test-cases/Actor/Doc/DocActorApiSharedDataSetGetValue)
++ [DocActorApiSharedDataSetDefaultValue](/../test-cases/Actor/Doc/DocActorApiSharedDataSetDefaultValue)
++ [DocActorApiSharedDataSetGetUndefined](/../test-cases/Actor/Doc/DocActorApiSharedDataSetGetUndefined)
+
+***
+
+[[NOTE={"guid":"9dc2c102-5799-4e3e-8148-449272301798"}]]
+[[ANCHOR={"id":"shared-data-api-set-shared-data-sync","visible":true}]]
+### **setSharedDataSync**
+```
+this.setSharedData(key[, value])
+```
+`Not documented yet`
+
+***
+
+[[NOTE={"guid":"a8723916-f1d5-4dba-89a9-3b42a00af8ca"}]]
+[[ANCHOR={"id":"shared-data-api-get-shared-data","visible":true}]]
+### **getSharedData**
+```
+this.getSharedData(key[, defaultValue])
+```
+
+[[NOTE={"guid":"797da89b-e891-48b1-83ef-b46ab9f15a43"}]]
+[[ANCHOR={"id":"efee1be3-bfb1-42a8-9871-bb1d8ec2a7d3","visible":true}]]
+#### **Method Description**
+
+Read [[REF=, ABS_Shared_Data]] set by other [[REF=, ABS_Actor]]s.
+If the the ***key*** is not found the resulting ***value*** will be the ***defaltValue*** if it exist, else it will be ***undefined***.
+
+```table
+Config(classHeading: )
+
+|Parameters                                                                                       |
+|Name        |Type               Default|         |Description                                    |
+|key         |[[REF=,MDN_string]]       |         |The ***key*** of the Shared Data.              |
+|defaultValue|<**any**>           |undefined|Value returned if the Shared Data is not found.|
+```
+
+```table
+Config(classHeading: )
+
+|Returns                                   |
+|Type           |Description               |
+|<**any**>|The resulting ***value***.|
+```
+
+[[NOTE={"guid":"77a4b653-54b6-4273-ae89-10f08c06a90c"}]]
+[[ANCHOR={"id":"aa7caa62-d2e0-46a6-8311-2a94669a1a87","visible":true}]]
+#### **Example using getSharedData**
+
+```javascript
+
+*run() {
+  let myBool = true;
+  this.setSharedData('demoKey1', 'Hello');
+  this.setSharedData('demoKey2', 5);
+  this.setSharedData('demoKey3', !myBool);
+
+  const a = getSharedData('demoKey1');                // a will be => "Hello"
+  const b = getSharedData('demoKey2');                // b will be => 5
+  const c = getSharedData('demoKey3');                // c will be => false
+  const d = getSharedData('demoKey4', 'not found');   // d will be => "not found"
+  const e = getSharedData('demoKey5');                // e will be => undefined
+}
+
+```
+
+[[NOTE={"guid":"18c22c2c-c2d8-443a-8289-92863e4d8c42"}]]
+[[ANCHOR={"id":"fda8aa47-afdd-46a5-b191-60b06181a406","visible":true}]]
+#### **Test Cases getSharedData**
++ [DocActorApiSharedDataSetGetValue](/../test-cases/Actor/Doc/DocActorApiSharedDataSetGetValue)
++ [DocActorApiSharedDataSetDefaultValue](/../test-cases/Actor/Doc/DocActorApiSharedDataSetDefaultValue)
++ [DocActorApiSharedDataSetGetUndefined](/../test-cases/Actor/Doc/DocActorApiSharedDataSetGetUndefined)
+
+***
+
+[[NOTE={"guid":"0aa08cd6-4838-42e5-a668-ed4245a035f1"}]]
+[[ANCHOR={"id":"shared-data-api-wait-for-shared-data","visible":true}]]
+### ***waitForSharedData**
+```
+this.waitForSharedData(key[, expectedValue])
+```
+
+[[NOTE={"guid":"8c4fa2cf-ad50-4b29-b2d9-68d48be14e0e"}]]
+[[ANCHOR={"id":"41ebe5d2-55ac-4c28-8304-57434d8334da","visible":true}]]
+#### **Method Description**
+
+Read [[REF=, ABS_Shared_Data]] set by other [[REF=, ABS_Actor]]s. If the [[REF=, ABS_Shared_Data]] is not set yet it will wait for it to be set.
+
+
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                                                                                                                                     |
+|Name         |Type               Default|         |Description                                                                                                                                                                                                 |
+|key          |[[REF=,MDN_string]]       |         |The ***key*** of the Shared Data.                                                                                                                                                                           |
+|expectedValue|&lt;**any**&gt;           |undefined|If ***expectedValue*** is not set the the method will return when or if the ***key*** is set.<br /> If ***expectedValue*** is set the method will return when the ***value*** is set to ***expectedValue***.|
+```
+
+```table
+Config(classHeading: )
+
+|Returns                                                                                                                                                                                                                                                                        |
+|Type           |Description                                                                                                                                                                                                                                                    |
+|&lt;**any**&gt;|The resulting ***value*** that awakens the [[REF=, ABS_Actor]].<br />`warning:` When the [[REF=, ABS_Actor]] gets the value it can already been changed by some other [[REF=, ABS_Actor]]. If the current value is nedeed, call **getSharedData*** when awaken.|
+```
+
+```table
+Config(classHeading: )
+
+|Async                    |
+|type      |Description   |
+|**yield***|auto generated|
+```
+
+[[NOTE={"guid":"7d699c29-c158-42f7-9ec0-fafd10b3cfbc"}]]
+[[ANCHOR={"id":"03b39b3a-0c5f-4d45-a262-529a99ee3d41","visible":true}]]
+#### **Example using waitForSharedData**
+
+```javascript
+
+*run() {
+  let myBool = true;
+  this.setSharedData('demoKey1', 'Hello');
+  this.setSharedData('demoKey2', 5);
+  this.setSharedData('demoKey3', !myBool);
+
+  const a = getSharedData('demoKey1');                // a will be => "Hello"
+  const b = getSharedData('demoKey2');                // b will be => 5
+  const c = getSharedData('demoKey3');                // c will be => false
+  const d = getSharedData('demoKey4', 'not found');   // d will be => "not found"
+  const e = getSharedData('demoKey5');                // e will be => undefined
+}
+```
+
+[[NOTE={"guid":"eca000d7-22fc-4759-bfbd-7916ac0a32b1"}]]
+[[ANCHOR={"id":"25062877-b7df-4e8a-88d5-151d762971d8","visible":true}]]
+#### **Test Cases waitForSharedData**
++ [DocActorApiSharedDataSetGetValue](/../test-cases/Actor/Doc/DocActorApiSharedDataSetGetValue)
++ [DocActorApiSharedDataWaitIteration](/../test-cases/Actor/Doc/DocActorApiSharedDataWaitIteration)
++ [DocActorApiSharedDataWaitMultiple](/../test-cases/Actor/Doc/DocActorApiSharedDataWaitMultiple)
+
+***
+
+[[NOTE={"guid":"ee72bdb1-716a-48c3-8a2d-a7ec27733573"}]]
+[[ANCHOR={"id":"shared-data-api-set-shared-data-actor","visible":true}]]
+### ***setSharedDataActor**
+```
+this.setSharedDataActor()
+```
+
+`Not documented yet`
+
+***
+
+[[NOTE={"guid":"28ec9f9d-87d8-4b44-9698-12d25d4969f8"}]]
+[[ANCHOR={"id":"shared-data-api-get-shared-data-actor","visible":true}]]
+### **getSharedDataActor**
+```
+this.getSharedDataActor()
+```
+
+`Not documented yet`
+
+***
+
+[[NOTE={"guid":"1e1a288a-46df-46c7-8918-c5293bb27634"}]]
+[[ANCHOR={"id":"shared-data-api-wait-for-shared-data-actor","visible":true}]]
+### ***waitForSharedDataActor**
+```
+this.waitForSharedDataActor()
+```
+
+`Not documented yet`
+
+***