View source for JsonStore Module

= Introduction =

The JsonStore module enables scripts and region modules to share structured data among themselves.  It should be considered experimental functionality - existing functions may still change.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module: 
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data.  JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key.  This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted.  Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function.  If this is not done then it will continue to occupy memory until the simulator is reset.

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.  

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
"elem"
"[0]"
"elem[0]"
"elem.[0]"
"{elem}.[0]"
"{foo.bar}.[0]" // this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo}.{bar}.[0]"
"foo.bar[0].goof" // this is a four token path: [{foo}, {bar}, [0], {goof}]
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =


Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll.  These methods are

<source lang="csharp">

    public delegate void TakeValueCallback(string s);

    public interface IJsonStoreModule
    {
        bool AttachObjectStore(UUID objectID);
        bool CreateStore(string value, ref UUID result);
        bool DestroyStore(UUID storeID);
        bool TestStore(UUID storeID);
        bool TestPath(UUID storeID, string path, bool useJson);
        bool SetValue(UUID storeID, string path, string value, bool useJson);
        bool RemoveValue(UUID storeID, string path);
        bool GetValue(UUID storeID, string path, bool useJson, out string value);

        void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
        void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
    }
</source>

'''TODO: Documentation on these methods.  At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore 
*JsonDestroyStore 
*JsonTestPath/JsonTestPathJson 
*JsonGetValue/JsonGetValueJson 
*JsonSetValue/JsonSetValueJson
*JsonReadNotecard 
*JsonWriteNotecard 

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned. 

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World' 
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
    }
}
</source>

=== integer status = JsonDestroyStore(key storeID)  ===

Destroy the JsonStore associated with the provided identifier. 

(In next release).  Returns 1 if the operation is successful.  Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5).  Return 1 if the operation is successful or if the store did not exit.  Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        integer res = JsonDestroyStore(storeID);
        
        llOwnerSay("Result " + (string)res);
    }
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard)  ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        
        requestID = JsonWriteNotecard(storeID, "", "nc1");
    }

    link_message(integer sender, integer ival, string sval, key id)
    {
        if (sender != -1) return;
        if (id == requestID)
            llOwnerSay("Notecard written");
    }
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID)  ===

Request that the Json encoded content of a notecard be decoded and &nbsp;placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
    touch_start(integer n)
    {        
        requestID = JsonReadNotecard(storeID, "", "nc1");
    }

    link_message(integer sender, integer ival, string sval, key id)
    {
        if (sender != -1) return;
        if (id == requestID)
            llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));
    }
}
</source>

=== int status = JsonTestPath(key storeID, string path)<br>int status = JsonTestPathJson(key storeID, string path)  ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

<source lang="lsl">
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        integer res = JsonTestPath(storeID, "Hello");
        
        llOwnerSay("Result " + (string)res);
    }
}
</source>

=== string value = JsonGetValue(key storeID, string path)<br>string jsonvalue = JsonGetValueJson(key storeID, string path)  ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

<source lang="lsl">
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        string res = JsonGetValue(storeID, "Hello");
        
        llOwnerSay("Result " + (string)res);
    }
}
</source>

=== int status = JsonSetValue(key storeID, string path, string value)<br>int status = JsonSetValue(key storeID, string path, string jsonvalue)  ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

<source lang="lsl">
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        
        integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");   
        llOwnerSay("Set result " + (string)intRes);
        
        string stringRes = JsonGetValue(storeID, "Pancake.Banana");
        llOwnerSay("Get result " + stringRes);
    }
}
</source>

=== int status = JsonRemoveValue(key storeID, string path)  ===

Remove from the store the value identified by the path.  

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist.  Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed.  Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
    touch_start(integer n)
    {
        key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
        
        integer intRes = JsonRemoveValue(storeID, "Hello");   
        llOwnerSay("Remove result " + (string)intRes);
        
        intRes = JsonTestPath(storeID, "Hello");
        llOwnerSay("TestPath result " + (string)intRes);
    }
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available.  This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson 
*JsonReadValue/JsonReadValueJson 

=== key requestID = JsonTakeValue(key storeID, string path)<br>key reqeustID = JsonTakeValueJson(key storeID, string path)  ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
    state_entry()
    {
        key requestID = JsonTakeValue(storeID,"Event.Lock");
    }

    link_message(integer sender, integer ival, integer sval, key id)
    {
        if (sender != -1) return;
        if (id == requestID)
        {
            // we now have a "lock"
            llOwnerSay("read: " + sval);

            // release the "lock" by placing the value back in the store
            llSetValue(storeID,"Event.Lock",sval);
        }
    }
}
</source>

=== key requestID = JsonReadValue(key storeID, string path)<br>key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]