infinispan 0.9.0 → 0.10.0

package/documentation/asciidoc/stories/assembly_client_usage_examples.adoc

@@ -1,15 +1,9 @@
 [id='client-usage-examples']
 :context: client-usage-examples
 = Using {hr_js} clients
-This section provides code examples that show you how to use {hr_js} clients to perform various operations.
+Take a look at some examples for using the {hr_js} client with {brandname}.
 
-include::{topics}/proc_working_single_entries_statistics.adoc[leveloffset=+1]
-include::{topics}/proc_using_conditional_operations.adoc[leveloffset=+1]
-include::{topics}/proc_working_multiple_entries.adoc[leveloffset=+1]
-include::{topics}/proc_working_ephemeral_data.adoc[leveloffset=+1]
-include::{topics}/proc_registering_event_listeners.adoc[leveloffset=+1]
-include::{topics}/proc_executing_scripts.adoc[leveloffset=+1]
-include::{topics}/proc_using_async_await.adoc[leveloffset=+1]
+include::{topics}/ref_client_usage.adoc[leveloffset=+1]
 
 // Restore the parent context.
 ifdef::parent-context[:context: {parent-context}]

package/documentation/asciidoc/stories/{assembly_configuration.adoc → assembly_installation_configuration.adoc}

@@ -1,8 +1,10 @@
-[id='client-configuration']
-:context: client-configuration
-= Configuring {hr_js} clients
-Configure {hr_js} clients to connect to {brandname} Server, use different media types for keys and values, and adjust levels for log messages.
+[id='install-configure']
+:context: install-configure
+= Installing and configuring {hr_js} clients
+Ensure your system meets requirements before installing the {hr_js} client.
+You can then configure {hr_js} clients to connect to {brandname} Server, use different media types for keys and values, and customize logging.
 
+include::{topics}/proc_installing_clients.adoc[leveloffset=+1]
 include::{topics}/proc_configuring_connections.adoc[leveloffset=+1]
 include::{topics}/proc_configuring_connections_xsite.adoc[leveloffset=+2]
 include::{topics}/proc_switching_clusters.adoc[leveloffset=+2]

package/documentation/asciidoc/titles/js_client.asciidoc

@@ -9,6 +9,7 @@ include::{topics}/attributes/community-attributes.adoc[]
 //Downstream
 //include::{topics}/attributes/downstream-attributes.adoc[]
 //:downstream:
+//:rhdg-install-npmrepo:
 
 //Title attributes
 :toc2:

package/documentation/asciidoc/titles/stories.adoc

@@ -1,6 +1,5 @@
 //Reference user stories or topics.
 //Please review authoring guidelines in the Contributors Guide.
 
-include::{stories}/assembly_getting_started.adoc[leveloffset=+1]
-include::{stories}/assembly_configuration.adoc[leveloffset=+1]
+include::{stories}/assembly_installation_configuration.adoc[leveloffset=+1]
 include::{stories}/assembly_client_usage_examples.adoc[leveloffset=+1]

package/documentation/asciidoc/topics/attributes/community-attributes.adoc

@@ -3,6 +3,6 @@
 
 :doc_home: https://infinispan.org/documentation/
 :download_url: https://infinispan.org/hotrod-clients
-:js_api_docs: https://docs.jboss.org/infinispan/hotrod-clients/javascript/1.0/apidocs/
+:node_docs: https://docs.jboss.org/infinispan/hotrod-clients/javascript/1.0/apidocs/
 :server_docs: https://infinispan.org/docs/stable/titles/server/server.html
 :code_tutorials: https://github.com/infinispan/infinispan-simple-tutorials/

package/documentation/asciidoc/topics/attributes/downstream-attributes.adoc

@@ -1,4 +1,2 @@
 :brandname: Data Grid
 :hr_js: Hot Rod JS
-
-:js_api_docs: https://access.redhat.com/webassets/avalon/d/red-hat-data-grid/8.2/node/

package/documentation/asciidoc/topics/code_examples/authentication-digest.js

@@ -1,5 +1,6 @@
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'},
-{
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
     authentication: {
       enabled: true,
       saslMechanism: 'DIGEST-MD5',

package/documentation/asciidoc/topics/code_examples/authentication-external.js

@@ -1,5 +1,6 @@
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'},
-{
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
     authentication: {
       enabled: true,
       saslMechanism: 'EXTERNAL'

package/documentation/asciidoc/topics/code_examples/authentication-oauthbearer.js

@@ -1,5 +1,6 @@
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'},
-{
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
     authentication: {
       enabled: true,
       saslMechanism: 'OAUTHBEARER',

package/documentation/asciidoc/topics/code_examples/authentication-plain.js

@@ -1,5 +1,6 @@
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'},
-{
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
     authentication: {
       enabled: true,
       saslMechanism: 'PLAIN',

package/documentation/asciidoc/topics/code_examples/authentication-scram.js

@@ -1,5 +1,6 @@
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'},
-{
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
     authentication: {
       enabled: true,
       saslMechanism: 'SCRAM-SHA-1',

package/documentation/asciidoc/topics/code_examples/await-single-entries.js

@@ -21,7 +21,7 @@ async function test() {
   let stats = await client.stats();
   console.log('Number of stores: ' + stats.stores);
   console.log('Number of cache hits: ' + stats.hits);
-  console.log('All stats: ' + JSON.stringify(stats, null, " "));
+  console.log('All statistics: ' + JSON.stringify(stats, null, " "));
 
   await client.disconnect();
 }

package/documentation/asciidoc/topics/code_examples/conditional-operations.js

@@ -1,6 +1,11 @@
 var infinispan = require('infinispan');
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
 
 connected.then(function (client) {
 
@@ -18,6 +23,7 @@ connected.then(function (client) {
   var clientGetMetaForReplace = showReplace.then(
       function() { return client.getWithMetadata('cond'); });
 
+  // Call the getWithMetadata method to retrieve the value and its metadata.
   var clientReplaceWithVersion = clientGetMetaForReplace.then(
       function(entry) {
         console.log('getWithMetadata(cond)=' + JSON.stringify(entry));

package/documentation/asciidoc/topics/code_examples/connection-multiple-servers.js

@@ -1,7 +1,11 @@
 var infinispan = require('infinispan');
 
 var connected = infinispan.client(
-  [{port: 11322, host: '127.0.0.1'}, {port: 11222, host: '127.0.0.1'}]);
+  [{port: 11322, host: '127.0.0.1'}, {port: 11222, host: '127.0.0.1'}]
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
 
 connected.then(function (client) {
 

package/documentation/asciidoc/topics/code_examples/data-types.js

@@ -1,8 +1,8 @@
 var infinispan = require('infinispan');
 
 var connected = infinispan.client(
-    {port: 11222, host: '127.0.0.1'}
-    , {
+    {port: 11222, host: '127.0.0.1'},
+    {
         dataFormat : {
             keyType: 'application/json',
             valueType: 'application/json'

package/documentation/asciidoc/topics/code_examples/ephemeral-data.js

@@ -1,6 +1,11 @@
 var infinispan = require('infinispan');
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
 
 connected.then(function (client) {
 
@@ -8,26 +13,26 @@ connected.then(function (client) {
 
   var clientGetMetaAndSize = clientPutExpiry.then(
     function() {
-      // Compute getWithMetadata and size in parallel
+      // Compute getWithMetadata and size in parallel.
       return Promise.all([client.getWithMetadata('expiry'), client.size()]);
     });
 
   var showGetMetaAndSize = clientGetMetaAndSize.then(
     function(values) {
-      console.log('before expiration:');
+      console.log('Before expiration:');
       console.log('getWithMetadata(expiry)=' + JSON.stringify(values[0]));
       console.log('size=' + values[1]);
     });
 
   var clientContainsAndSize = showGetMetaAndSize.then(
     function() {
-      sleepFor(1100); // Sleep to force expiration
+      sleepFor(1100); // Sleep to force expiration.
       return Promise.all([client.containsKey('expiry'), client.size()]);
     });
 
   var showContainsAndSize = clientContainsAndSize.then(
     function(values) {
-      console.log('after expiration:');
+      console.log('After expiration:');
       console.log('containsKey(expiry)=' + values[0]);
       console.log('size=' + values[1]);
     });
@@ -43,5 +48,5 @@ connected.then(function (client) {
 
 function sleepFor(sleepDuration){
   var now = new Date().getTime();
-  while(new Date().getTime() < now + sleepDuration){ /* do nothing */ }
+  while(new Date().getTime() < now + sleepDuration){ /* Do nothing. */ }
 }

package/documentation/asciidoc/topics/code_examples/hello-world.js

@@ -1,8 +1,20 @@
 var infinispan = require('infinispan');
 
 // Connect to {brandname} Server.
+// Use an existing cache named "myCache".
 var connected = infinispan.client(
-  {port: 11222, host: '127.0.0.1'}, {cacheName: 'myCache'});
+  {port: 11222, host: '127.0.0.1'},
+  {
+    cacheName: 'myCache',
+    clientIntelligence: 'BASIC',
+    authentication: {
+      enabled: true,
+      saslMechanism: 'DIGEST-MD5',
+      userName: 'username',
+      password: 'changeme'
+    }
+  }
+);
 
 connected.then(function (client) {
 

package/documentation/asciidoc/topics/code_examples/key-value-converter.js

@@ -11,7 +11,7 @@ var connected = infinispan.client(
 );
 
 connected.then(function (client) {
-
+    // Include the remote event converter to avoid unnecessary roundtrips.
     var opts = {
         converterFactory : {
             name: "key-value-with-previous-converter-factory"
@@ -22,9 +22,8 @@ connected.then(function (client) {
 
     var clientAddListeners = clientAddListenerCreate.then(
         function(listenerId) {
-            // Multiple callbacks can be associated with a single client-side listener.
-            // This is achieved by registering listeners with the same listener id
-            // as shown in the example below.
+            // Associate multiple callbacks with a single client-side listener.
+            // To do this, register listeners with the same listener ID.
             var clientAddListenerModify =
                 client.addListener('modify', logEvent("Modified"), {opts, listenerId: listenerId});
 

package/documentation/asciidoc/topics/code_examples/multiple-entries.js

@@ -1,6 +1,17 @@
 var infinispan = require('infinispan');
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
+    cacheName: 'myCache',
+    authentication: {
+        enabled: true,
+        saslMechanism: 'DIGEST-MD5',
+        userName: 'username',
+        password: 'changeme'
+    }
+  }
+);
 
 connected.then(function (client) {
   var data = [
@@ -25,7 +36,7 @@ connected.then(function (client) {
   var showIterated = clientIterator.then(
     function(it) {
       function loop(promise, fn) {
-        // Simple recursive loop over iterator's next() call
+        // Simple recursive loop over the iterator's next() call.
         return promise.then(fn).then(function (entry) {
           return entry.done
             ? it.close().then(function () { return entry.value; })

package/documentation/asciidoc/topics/code_examples/register-event-listener.js

@@ -1,6 +1,11 @@
 var infinispan = require('infinispan');
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
 
 connected.then(function (client) {
 
@@ -8,9 +13,8 @@ connected.then(function (client) {
 
     var clientAddListeners = clientAddListenerCreate.then(
         function(listenerId) {
-            // Multiple callbacks can be associated with a single client-side listener.
-            // This is achieved by registering listeners with the same listener id
-            // as shown in the example below.
+            // Associate multiple callbacks with a single client-side listener.
+            // To do this, register listeners with the same listener ID.
             var clientAddListenerModify =
                 client.addListener('modify', onModify, {listenerId: listenerId});
 

package/documentation/asciidoc/topics/code_examples/sample-script-execute.js

@@ -1,7 +1,12 @@
 var infinispan = require('infinispan');
 var readFile = Promise.denodeify(require('fs').readFile);
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
 
 connected.then(function (client) {
 

package/documentation/asciidoc/topics/code_examples/single-entries.js

@@ -1,6 +1,17 @@
 var infinispan = require('infinispan');
 
-var connected = infinispan.client({port: 11222, host: '127.0.0.1'});
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'},
+  {
+    cacheName: 'myCache',
+    authentication: {
+        enabled: true,
+        saslMechanism: 'DIGEST-MD5',
+        userName: 'username',
+        password: 'changeme'
+    }
+  }
+);
 
 connected.then(function (client) {
 
@@ -25,7 +36,7 @@ connected.then(function (client) {
     function(stats) {
       console.log('Number of stores: ' + stats.stores);
       console.log('Number of cache hits: ' + stats.hits);
-      console.log('All stats: ' + JSON.stringify(stats, null, " "));
+      console.log('All statistics: ' + JSON.stringify(stats, null, " "));
     });
 
   return showStats.finally(

package/documentation/asciidoc/topics/proc_configuring_connections.adoc

@@ -2,6 +2,14 @@
 = Configuring {brandname} connections
 Configure {hr_js} clients to connect to {brandname} Server.
 
+If add multiple server addresses to the configuration, the {hr_js} client loops through them until it finds a node to which it can connect.
+
+However, you only need to add one {brandname} Server address for the client to receive the entire cluster topology.
+If the {hr_js} client connects to a single server instance that is a member of a cluster, the client gets the address information for all nodes.
+
+Because {hr_js} clients are topology aware, if a connection to one {brandname} Server breaks, the client retries any incomplete operations on other nodes in the cluster.
+Likewise, if client listener that is registered on one {brandname} Server fails or leaves the cluster, the client transparently migrates the listener registration to another node in the cluster so that it can continue receiving events.
+
 .Prerequisites
 
 * Install the {hr_js} client.
@@ -15,12 +23,3 @@ Configure {hr_js} clients to connect to {brandname} Server.
 ----
 include::code_examples/connection-multiple-servers.js[]
 ----
-
-The preceding configuration example includes connection details for two servers.
-When you add multiple server addresses to the configuration, the {hr_js} client loops through them until it finds a node to which it can connect.
-
-However, you only need to add one {brandname} Server address for the client to receive the entire cluster topology.
-If the {hr_js} client connects to a single server instance that is a member of a cluster, the client gets the address information for all nodes.
-
-Because {hr_js} clients are topology aware, if a connection to one {brandname} Server breaks, the client retries any incomplete operations on other nodes in the cluster.
-Likewise, if client listener that is registered on one {brandname} Server fails or leaves the cluster, the client transparently migrates the listener registration to another node in the cluster so that it can continue receiving events.

package/documentation/asciidoc/topics/proc_installing_clients.adoc

@@ -22,19 +22,37 @@ endif::downstream[]
 ifdef::community[]
 * Install the `infinispan` client as follows:
 +
-[source,bash,options="nowrap",subs=attributes+]
+[source,options="nowrap",subs=attributes+]
 ----
-$ npm i infinispan
+npm install infinispan
 ----
 endif::community[]
 
 //Downstream content
-ifdef::downstream[]
+ifdef::rhdg-install-npmrepo[]
+. Add the Red Hat repository to your NPM configuration.
++
+You can use the `npm config` command or add the following to an `.npmrc` file in your project:
++
+[source,options="nowrap",subs=attributes+]
+----
+@redhat:registry=https://npm.registry.redhat.com
+registry=https://registry.npmjs.org/
+----
+
+. Install the {hr_js} client as follows:
++
+[source,options="nowrap",subs=attributes+]
+----
+npm install @redhat/infinispan
+----
+endif::rhdg-install-npmrepo[]
+ifdef::rhdg-install-package[]
 . Download and extract the `redhat-datagrid-<version>-nodejs-client.zip` from the {portal}.
 . Install the `tgz` package from the extracted directory as in the following example:
 +
 [source,bash,options="nowrap",subs=attributes+]
 ----
-$ npm install /path/to/redhat-datagrid-<version>-nodejs-client/infinispan-<version>.tgz
+npm install /path/to/redhat-datagrid-<version>-nodejs-client/infinispan-<version>.tgz
 ----
-endif::downstream[]
+endif::rhdg-install-package[]

package/documentation/asciidoc/topics/ref_client_usage.adoc

@@ -0,0 +1,116 @@
+[id='client-usage_{context}']
+= {hr_js} client examples
+
+After you install and configure your {hr_js} client, start using it by trying out some basic cache operations before moving on to more complex interactions with {brandname}.
+
+== Hello world
+
+Create a cache named "myCache" on {brandname} Server then add and retrieve an entry.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/hello-world.js[]
+----
+
+== Working with entries and retrieving cache statistics
+
+Add, retrieve, remove single entries and view statistics for the cache.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/single-entries.js[]
+----
+
+== Working with multiple cache entries
+
+Create multiple cache entries with simple recursive loops.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/multiple-entries.js[]
+----
+
+== Using Async and Await constructs
+
+Node.js provides `async` and `await` constructs that can simplify cache operations.
+
+.Single cache entries
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/await-single-entries.js[]
+----
+
+.Multiple cache entries
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/await-multiple-entries.js[]
+----
+
+== Running server-side scripts
+
+You can add custom scripts to {brandname} Server and then run them from {hr_js} clients.
+
+.Sample script
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/sample-script.js[]
+----
+
+.Script execution
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/sample-script-execute.js[]
+----
+
+== Registering event listeners
+
+Event listeners notify {hr_js} clients when cache updates occur, including when entries are created, modified, removed, or expired.
+
+[NOTE]
+====
+Events for entry creation and modification notify clients about keys and values.
+Events for entry removal and expiration notify clients about keys only.
+====
+
+.Event listener registration
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/register-event-listener.js[]
+----
+
+You can tune notifications from event listeners to avoid unnecessary roundtrips with the `key-value-with-previous-converter-factory` converter.
+This allows you to, for example, find out values associated with keys within the event instead of retrieving them afterwards.
+
+.Remote event converter
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/key-value-converter.js[]
+----
+
+[TIP]
+====
+You can add custom converters to {brandname} Server.
+See the link:{doc_home}[{brandname} documentation] for information.
+====
+
+== Using conditional operations
+
+The Hot Rod protocol stores metadata about values in {brandname}.
+This metadata provides a deterministic factor that lets you perform cache operations for certain conditions.
+For example, if you want to replace the value of a key if the versions do not match.
+
+Use the `getWithMetadata` method to retrieve metadata associated with the value for a key.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/conditional-operations.js[]
+----
+
+== Working with ephemeral data
+
+Use the `getWithMetadata` and `size` methods expire cache entries.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/ephemeral-data.js[]
+----