Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
service:jsondb [2022/11/27 15:40] – created: A basic start of a guide for using the JSON database service Nightfoxservice:jsondb [2022/12/08 14:01] (current) – [Best Practices] Nightfox
Line 3: Line 3:
 For instance, a BBS might provide game scores for a particular game; that particular door game could be installed on multiple BBSes and post their user scores to the host BBS, which would provide a central place to host scores for the door, so that there could be a multi-BBS top scores list.  Another example is a global one-liners wall where people from multiple BBSes could post a one-liner, and the one-liners could be hosted by a BBS and accessed from any other BBS.\\ For instance, a BBS might provide game scores for a particular game; that particular door game could be installed on multiple BBSes and post their user scores to the host BBS, which would provide a central place to host scores for the door, so that there could be a multi-BBS top scores list.  Another example is a global one-liners wall where people from multiple BBSes could post a one-liner, and the one-liners could be hosted by a BBS and accessed from any other BBS.\\
 \\ \\
-Synchronet provides this via the script json-service.js (in the exec directory).  To enable the JSON service, add the following lines to your ctrl/services.ini if not already there:+===== Updating services.ini and json-service.ini ===== 
 +Synchronet provides this via the script json-service.js (in the exec directory).  To enable the JSON service, add the following lines to your ''[[dir:ctrl]]''/''[[config:services.ini]]'' if not already there:
 <file> <file>
 [JSON] [JSON]
Line 12: Line 13:
 Note the port number is 10088.  This is a common port number to use for the JSON service.\\ Note the port number is 10088.  This is a common port number to use for the JSON service.\\
 \\ \\
-For storing data to be accessed this way, Synchronet uses the concept of JSON "databases".  Each JSON database is given a name and are configured in ctrl/json-service.ini.  For instance, there is a one-liners script in xtrn/oneliners, and if you want to host one-liners, you would need these lines in ctrl/json-service.ini:+For storing data to be accessed this way, Synchronet uses the concept of JSON "databases".  Each JSON database is given a name and are configured in ''[[dir:ctrl]]''/json-service.ini.  For instance, there is a one-liners script in xtrn/oneliners, and if you want to host one-liners, you would need these lines in ctrl/json-service.ini:
 <file> <file>
 [oneliners] [oneliners]
Line 21: Line 22:
  
  
-Reading from & writing to a JSON database +===== Reading from & writing to a JSON database=====  
------------------------------------------ +In a JavaScript mod/door/game (a 'client'), first you will need to have your script include json-client.js (in the ''[[dir:exec]]''/''[[dir:load]]'' directory).  Before you use JSONClient, add this to your JS script: 
-Most basically, all that is really required to interact with a JSON database is writing (adding/updating data) and reading (getting data from the JSON database).  The top of json-client.js (in sbbs/exec/load) has a list of relevant functions for working with a JSON database.  Assuming the JSON client object is jsonClient, the two functions for reading from and writing to a JSON database are:+  require("json-client.js", "JSONClient"); 
 +Then, create a JSONClient object.  When doing so, you will need to provide the server (host) name/IP address and the port number as parameters.  For example, to connect to your own BBS (you could use "127.0.0.1" or "localhost"): 
 +  var jsonClient = new JSONClient("127.0.0.1", 10088); 
 +Most basically, all that is really required to interact with a JSON database is writing (adding/updating data) and reading (getting data from the JSON database).  The top of json-client.js has a list of relevant functions for working with a JSON database.  The two functions for reading from and writing to a JSON database are defined as follows:
  
   jsonClient.read(scope,location,lock)   jsonClient.read(scope,location,lock)
Line 35: Line 39:
       }       }
   }   }
-A location of scores.player1.TestGame specifies the value of the TestGame property under player1 under scores in the JSON object. +A location of scores.player1.TestGame specifies the value of the TestGame property under player1 under scores in the JSON object.\\ 
 +\\
 For the 'lock' parameter in the JSON client functions, lock objects are often used to protect against problems if multiple things try to read/write the same value at the same time.  There are a few lock values that can be specified for the lock parameter: For the 'lock' parameter in the JSON client functions, lock objects are often used to protect against problems if multiple things try to read/write the same value at the same time.  There are a few lock values that can be specified for the lock parameter:
   LOCK_READ = 1   LOCK_READ = 1
Line 45: Line 49:
  
 The subscribe function can be used to subscribe to get updates when data at a given JSON location changes: The subscribe function can be used to subscribe to get updates when data at a given JSON location changes:
-  JSONClient.subscribe(scope,location)+  jsonClient.subscribe(scope,location)
  
 When you subscribe to a certain data location, it's important to specify a callback function.  For instance: When you subscribe to a certain data location, it's important to specify a callback function.  For instance:
Line 53: Line 57:
   }   }
  
 +Also, when you are done using your JSONClient object, it is generally a good practice to explicitly have it disconnect from the server, by calling the 'disconnect' method:
 +  jsonClient.disconnect();
  
- +===== Best Practices ===== 
-Special files: commands.js and service.js +When there could be concurrent access to the same data (i.e., multiple clients that might need to write to the same location in the JSON data), it is a good practice to lock that location for writing when you're writing an update.  The idea is to prevent two or more systems from writing data to the same place at the same time, where one write might overwrite another write, or perhaps another system reading data would get the wrong copy of the data just as it has been updated, etc.\\ 
------------------------------------------+\\ 
 +Note that the write function has a lock parameter: 
 +  JSONCLient.write(scope, data, location, lock) 
 +If you specify the lock parameter (such as 2, the write lock), it will lock, write, and unlock all at once.  For instance: 
 +  var JSON_DB_LOCK_WRITE = 2; 
 +  jsonClient.write("scores", "player1.TestGame", scoresData, JSON_DB_LOCK_WRITE); 
 +\\ 
 +There are also a couple of functions, lock() and unlock() that you can use for locking and unlocking: 
 +  jsonClient.lock(scope,location,lock); 
 +  jsonClient.unlock(scope,location); 
 +When you use those, then you would //not// specify the lock parameter for write().  If you lock before you write, you know that you can read after that and whatever value you get back will not have changed by some other system.\\ 
 +\\ 
 +For instance: 
 +  var JSON_DB_LOCK_READ = 1; 
 +  var JSON_DB_LOCK_WRITE = 2; 
 +  var jsonClient = new JSONClient("servername", 10088); 
 +  jsonClient.lock("scores", "player1.TestGame", JSON_DB_LOCK_WRITE); 
 +  var scoresData = jsonClient.read("scores", "player1.TestGame"); 
 +  // Change scoresData ... 
 +  jsonClient.write("scores", "player1.TestGame", scoresData); 
 +  jsonClient.unlock("scores", "player1.TestGame"); 
 +   
 +Note that you need to either specify the lock parameter for write() OR call lock() & unlock() without specifying a lock parameter for write().  If you both call lock() with 2 (write lock) AND specify 2 for the lock parameter for write(), then it will not update the data on the server because you'd have 2 locks interfering with each other. 
 +===== Special files: commands.js and service.js =====
 There are a couple of additional JavaScript files you can create for your JSON database:\\ There are a couple of additional JavaScript files you can create for your JSON database:\\
   * commands.js: This can be used to deny (or allow) access to perform certain JSON commands, by specifying a function for this.QUERY.  It returns a boolean; Note that a return value of false allows a command, and a return value of true denies the command.  For instance, you could prevent client programs from deleting data from the JSON database if you wish.  For instance, this one (One Liners) allows subscribe, unsubscribe, read, slice, and push or anything from the current computer: https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/oneliners/commands.js   * commands.js: This can be used to deny (or allow) access to perform certain JSON commands, by specifying a function for this.QUERY.  It returns a boolean; Note that a return value of false allows a command, and a return value of true denies the command.  For instance, you could prevent client programs from deleting data from the JSON database if you wish.  For instance, this one (One Liners) allows subscribe, unsubscribe, read, slice, and push or anything from the current computer: https://gitlab.synchro.net/main/sbbs/-/blob/master/xtrn/oneliners/commands.js

Trace: