infinispan 0.8.0 → 0.10.0

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

@@ -0,0 +1,64 @@
+var infinispan = require('infinispan');
+
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
+
+connected.then(function (client) {
+
+    var clientAddListenerCreate = client.addListener('create', onCreate);
+
+    var clientAddListeners = clientAddListenerCreate.then(
+        function(listenerId) {
+            // 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});
+
+            var clientAddListenerRemove =
+                client.addListener('remove', onRemove, {listenerId: listenerId});
+
+            return Promise.all([clientAddListenerModify, clientAddListenerRemove]);
+        });
+
+    var clientCreate = clientAddListeners.then(
+        function() { return client.putIfAbsent('eventful', 'v0'); });
+
+    var clientModify = clientCreate.then(
+        function() { return client.replace('eventful', 'v1'); });
+
+    var clientRemove = clientModify.then(
+        function() { return client.remove('eventful'); });
+
+    var clientRemoveListener =
+        Promise.all([clientAddListenerCreate, clientRemove]).then(
+            function(values) {
+                var listenerId = values[0];
+                return client.removeListener(listenerId);
+            });
+
+    return clientRemoveListener.finally(
+        function() { return client.disconnect(); });
+
+}).catch(function(error) {
+
+    console.log("Got error: " + error.message);
+
+});
+
+function onCreate(key, version) {
+    console.log('[Event] Created key: ' + key +
+        ' with version: ' + JSON.stringify(version));
+}
+
+function onModify(key, version) {
+    console.log('[Event] Modified key: ' + key +
+        ', version after update: ' + JSON.stringify(version));
+}
+
+function onRemove(key) {
+    console.log('[Event] Removed key: ' + key);
+}

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

@@ -0,0 +1,33 @@
+var infinispan = require('infinispan');
+var readFile = Promise.denodeify(require('fs').readFile);
+
+var connected = infinispan.client(
+  {port: 11222, host: '127.0.0.1'}
+  {
+    // Configure client connections with authentication and encryption here.
+  }
+);
+
+connected.then(function (client) {
+
+  var addScriptFile = readFile('sample-script.js').then(
+    function(file) {
+      return client.addScript('sample-script', file.toString());
+    });
+
+  var clientExecute = addScriptFile.then(
+    function() {
+      return client.execute('sample-script', {k: 'exec-key', v: 'exec-value'});
+    });
+
+  var showExecute = clientExecute.then(
+    function(ret) { console.log('Script execution returned: ' + ret); });
+
+  return showExecute.finally(
+    function() { return client.disconnect(); });
+
+}).catch(function(error) {
+
+  console.log("Got error: " + error.message);
+
+});

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

@@ -0,0 +1,3 @@
+// mode=local,language=javascript,parameters=[k, v],datatype='text/plain; charset=utf-8'
+cache.put(k, v);
+cache.get(k);

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

@@ -0,0 +1,49 @@
+var infinispan = require('infinispan');
+
+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 clientPut = client.put('key', 'value');
+
+  var clientGet = clientPut.then(
+      function() { return client.get('key'); });
+
+  var showGet = clientGet.then(
+      function(value) { console.log('get(key)=' + value); });
+
+  var clientRemove = showGet.then(
+      function() { return client.remove('key'); });
+
+  var showRemove = clientRemove.then(
+      function(success) { console.log('remove(key)=' + success); });
+
+  var clientStats = showRemove.then(
+    function() { return client.stats(); });
+
+  var showStats = clientStats.then(
+    function(stats) {
+      console.log('Number of stores: ' + stats.stores);
+      console.log('Number of cache hits: ' + stats.hits);
+      console.log('All statistics: ' + JSON.stringify(stats, null, " "));
+    });
+
+  return showStats.finally(
+      function() { return client.disconnect(); });
+
+}).catch(function(error) {
+
+  console.log("Got error: " + error.message);
+
+});

package/documentation/asciidoc/topics/config_examples/logging.json

@@ -0,0 +1,14 @@
+{
+  "appenders": {
+    "test": {
+      "type": "fileSync",
+      "filename": "my-log-file.log"
+    }
+  },
+  "categories": {
+    "default": {
+      "appenders": ["test"],
+      "level": "trace"
+    }
+  }
+}

package/documentation/asciidoc/topics/proc_configuring_authentication.adoc

@@ -0,0 +1,16 @@
+[id='configuring-authentication_{context}']
+= Configuring authentication
+
+{brandname} Server uses different SASL mechanisms to authenticate {hr_js} client connections.
+
+.Prerequisites
+
+* Create {brandname} users.
+* Add the SASL authentication mechanism to the Hot Rod connector in your {brandname} Server configuration.
+
+.Procedure
+
+. Open the {hr_js} client configuration for editing.
+. Add an `authentication` method that sets the `enabled: true` flag.
+. Specify a value for the `saslMechanism` parameter that matches the SASL authentication mechanism for the Hot Rod connector.
+. Configure any parameters specific to the SASL authentication mechanism as appropriate.

package/documentation/asciidoc/topics/proc_configuring_connections.adoc

@@ -0,0 +1,25 @@
+[id='configuring-connections_{context}']
+= 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.
+* Have at least one running {brandname} Server instance.
+
+.Procedure
+
+* Specify hostnames and ports for {brandname} Server in the client configuration.
++
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/connection-multiple-servers.js[]
+----

package/documentation/asciidoc/topics/proc_configuring_connections_xsite.adoc

@@ -0,0 +1,18 @@
+[id='configuring-connections-cross-site_{context}']
+= Defining {brandname} clusters in client configuration
+When you set up {brandname} clusters in separate data centers to perform cross-site replication, you can add connection details for the different sites to the client configuration.
+
+.Prerequisites
+
+* Install the {hr_js} client.
+* Configure {brandname} for cross-site replication.
+
+.Procedure
+
+. Add a `clusters` definition to your configuration.
+. Add `name` and `servers` definitions for each {brandname} cluster.
++
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/connection-xsite.js[]
+----

package/documentation/asciidoc/topics/proc_configuring_data_formats.adoc

@@ -0,0 +1,30 @@
+[id='configuring-data-formats_{context}']
+= Configuring data formats
+{hr_js} clients can handle keys and values as native JavaScript Object Notation (JSON) objects or as String objects.
+By default, clients handle entries as String objects.
+If you want to transmit data to {brandname} Server in JSON format, then you must configure the {hr_js} client.
+
+//Community content
+ifdef::community[]
+Starting at version 0.6, {hr_js} clients support native JSON objects as keys and values.
+Earlier versions of the client support keys and values as String only.
+endif::community[]
+
+[NOTE]
+====
+Script operations support String key/value pairs and String parameters only.
+====
+
+.Procedure
+
+. Add a `dataFormat` configuration to your client.
+. Set the data format for keys and values as appropriate with the `keyType` and `valueType` parameters.
+
+Keys and values can have different media types.
+For JSON objects, specify `application/json`.
+For String objects, specify `text/plain` or omit the parameter to use the default.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/data-types.js[]
+----

package/documentation/asciidoc/topics/proc_configuring_encryption.adoc

@@ -0,0 +1,15 @@
+[id='configuring-encryption_{context}']
+= Configuring encryption
+
+{brandname} Server can enforce different types of SSL/TLS encryption to secure {hr_js} client connections.
+
+.Prerequisites
+
+* Create a trust store that {hr_js} clients can use to verify {brandname} Server identities.
+* If you configure {brandname} Server to validate or authenticate client certificates, create a keystore as appropriate.
+
+.Procedure
+
+. Open the {hr_js} client configuration for editing.
+. Add an `ssl` method that sets the `enabled: true` flag.
+. Provide any other configuration specific to the type of encryption you use.

package/documentation/asciidoc/topics/proc_configuring_logging.adoc

@@ -0,0 +1,28 @@
+[id='configuring-logging_{context}']
+= Configuring logging
+
+{hr_js} clients use `log4js`, which you can modify by providing configuration in JSON format.
+
+.Procedure
+
+. Create a logging configuration in JSON format.
++
+For example, the following JSON configures an appender that writes TRACE level log events to file:
++
+[source,json,options="nowrap",subs=attributes+]
+----
+include::config_examples/logging.json[]
+----
++
+. Add the `var log4js = require('log4js')` statement to the {hr_js} client configuration.
+. Specify the path to your JSON logging configuration with the `log4js.configure()` method, as in the following example:
++
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/logging-configuration.js[]
+----
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://www.npmjs.com/package/log4js[log4js]
+* link:https://github.com/log4js-node/log4js-node/tree/master/examples[log4js-node examples]

package/documentation/asciidoc/topics/proc_installing_clients.adoc

@@ -0,0 +1,58 @@
+[id='installing-clients_{context}']
+= Installing {hr_js} clients
+{brandname} provides a distribution of the {hr_js} client that you can install via the NPM package manager.
+
+.Prerequisites
+
+* Node.js version `12` or `14`.
+//Community content
+ifdef::community[]
+* {brandname} Server 9.4.x or later.
++
+Use js-client `0.7` for {brandname} Server `8.2.x` to `9.3.x`.
+endif::community[]
+//Downstream content
+ifdef::downstream[]
+* {brandname} Server {ProductVersion}.
+endif::downstream[]
+
+.Procedure
+
+//Community content
+ifdef::community[]
+* Install the `infinispan` client as follows:
++
+[source,options="nowrap",subs=attributes+]
+----
+npm install infinispan
+----
+endif::community[]
+
+//Downstream content
+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
+----
+endif::rhdg-install-package[]

package/documentation/asciidoc/topics/proc_switching_clusters.adoc

@@ -0,0 +1,17 @@
+[id='switching-clusters_{context}']
+= Manually switching {brandname} clusters
+Change the {brandname} cluster to which the {hr_js} client is connectioned.
+
+.Prerequisites
+
+* Define {brandname} clusters in the {hr_js} client configuration.
+
+.Procedure
+
+. Call the `switchToCluster(clusterName)` method to force the client to switch to a {brandname} cluster that is defined in the client configuration.
+. Call the `switchToDefaultCluster()` method to start using the initial {brandname} cluster.
++
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/connection-xsite-cluster-switch.js[]
+----

package/documentation/asciidoc/topics/ref_authentication_mechanisms.adoc

@@ -0,0 +1,68 @@
+[id='authentication-mechanisms_{context}']
+= SASL authentication mechanisms
+
+{hr_js} clients can use the following SASL authentication mechanisms to connect to {brandname} Server.
+
+[discrete]
+== PLAIN
+
+Sends credentials in plain text (unencrypted) over the wire in a way that is similar to HTTP `BASIC` authentication.
+
+[IMPORTANT]
+====
+To secure {brandname} credentials, you should use `PLAIN` authentication only in combination with TLS encryption.
+====
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/authentication-plain.js[]
+----
+
+[discrete]
+== DIGEST-MD5
+
+Uses the MD5 hashing algorithm in addition to nonces to encrypt credentials.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/authentication-digest.js[]
+----
+
+[discrete]
+== SCRAM
+
+Uses salt values in addition to hashing algorithms and nonce values to encrypt credentials.
+Hot Rod endpoints support `SCRAM-SHA-1`, `SCRAM-SHA-256`, `SCRAM-SHA-384`, `SCRAM-SHA-512` hashing algorithms, in order of strength.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/authentication-scram.js[]
+----
+
+//Community content
+ifdef::community[]
+[discrete]
+== EXTERNAL
+
+Uses client certificates to provide valid identities to {brandname} Server and enable encryption.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/authentication-external.js[]
+----
+
+
+[discrete]
+== OAUTHBEARER
+
+Uses tokens obtained via an OAuth 2.0 provider to securely connect to {brandname} Server.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/authentication-oauthbearer.js[]
+----
+endif::community[]
+
+[role="_additional-resources"]
+.Additional resources
+* link:{server_docs}#endpoint-authentication[Configuring Endpoint Authentication Mechanisms]

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[]
+----

package/documentation/asciidoc/topics/ref_encryption.adoc

@@ -0,0 +1,71 @@
+[id='encryption_{context}']
+= Encryption types
+
+{hr_js} clients can use different types of encryption to negotiate secure connections with {brandname} Server.
+
+[discrete]
+== {brandname} Server identities
+
+For basic encryption, you can add the signing certificate, or CA bundle, for {brandname} Server certificates to your configuration as follows:
+
+[NOTE]
+====
+To verify certificates issued to {brandname} Server, {hr_js} clients require either the full certificate chain or a partial chain that starts with the Root CA.
+====
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/encryption-trust-certs.js[]
+----
+
+[discrete]
+== Trust stores
+
+You can add trust stores in `PKCS12` or `PFX` format as follows:
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/encryption-crypto-store.js[]
+----
+
+[discrete]
+== Client certificate authentication
+
+If you enable client certificate authentication in {brandname} Server configuration, add a keystore as in the following example:
+
+[NOTE]
+====
+You must configure the {hr_js} client with the `EXTERNAL` authentication mechanism when using client certificate authentication.
+====
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/encryption-private-key.js[]
+----
+
+[discrete]
+== Server Name Indication (SNI)
+
+If you use SNI to allow {hr_js} clients to request {brandname} Server hostnames, set a value for the `sniHostName` parameter that matches a hostname in the {brandname} Server configuration.
+
+[NOTE]
+====
+The `sniHostName` parameter defaults to `localhost`.
+====
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/encryption-sni-hostname.js[]
+----
+
+[TIP]
+====
+{hr_js} clients do not allow self-signed certificates by default, which can cause issues in development or test environments where no public certificate authority (CA) key is available.
+
+Check out the link:{code_tutorials}[{brandname} code tutorials] for an example on creating signed certificates with the Java keytool.
+====
+
+[role="_additional-resources"]
+.Additional resources
+* link:{server_docs}#interfaces-endpoints[Network interfaces and endpoints]
+* link:{server_docs}#endpoint-encryption[Encrypting {brandname} Server connections]