infinispan 0.9.0 → 0.11.0

package/documentation/asciidoc/topics/ref_client_usage.adoc

@@ -0,0 +1,128 @@
+[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[]
+----
+
+== Working with queries
+
+Use the `query` method to perform queries on your caches.
+You must configure {hr_js} client to have `application/x-protostream` data format for values in your caches.
+
+[source,javascript,options="nowrap",subs=attributes+]
+----
+include::code_examples/queries.js[]
+----
+
+See link:{query_docs}[Querying {brandname} caches] for more information.

package/lib/codec.js

@@ -6,6 +6,9 @@
       , INT = Math.pow(2, 31);
 
   var _ = require('underscore');
+  var protobuf = require('protobufjs');
+  var path = require('path');
+
   var f = require('./functional');
   var utils = require('./utils');
 
@@ -16,8 +19,11 @@
   exports.encodeVLong = f.lift(doEncodeVLong, _.identity);
   exports.encodeJSON = f.lift(doEncodeJSON, _.identity);
   exports.encodeBytes = f.lift(doEncodeBytes, _.identity);
+  exports.encodeBytesWithLength = f.lift(doEncodeBytesWithLength, _.identity);
   exports.encodeString = f.lift(doEncodeString, _.identity);
   exports.encodeSignedInt = f.lift(doEncodeSignedInt, _.identity);
+  exports.encodeProtobuf = f.lift(doEncodeProtobuf, _.identity);
+  exports.encodeQuery = f.lift(doEncodeQuery,_.identity);
 
   exports.decodeUByte = f.lift(doDecodeUByte, _.identity);
   exports.decodeVInt = f.lift(doDecodeVInt, _.identity);
@@ -29,6 +35,8 @@
   exports.decodeSignedInt = f.lift(doDecodeSignedInt, _.identity);
   exports.decodeVariableBytes = f.lift(doDecodeVariableBytes, _.identity);
   exports.decodeShort = f.lift(doDecodeShort, _.identity);
+  exports.decodeProtobuf = f.lift(doDecodeProtobuf, _.identity);
+  exports.decodeQuery = f.lift(doDecodeQuery,_.identity);
 
   exports.lastDecoded = function(values) {
     return values[0];
@@ -79,10 +87,54 @@
     return _.compose(updateEncOffset(bytebuf), checkedWriteBytes(bytebuf))(bytes);
   }
 
+  function doEncodeBytesWithLength(bytebuf, bytes) {
+    return _.compose(updateEncOffset(bytebuf), checkedWriteBytesWithLength(bytebuf))(bytes);
+  }
+
   function doEncodeSignedInt(bytebuf, num) {
     return _.compose(updateEncOffset(bytebuf), checkedWriteSignedInt(bytebuf), zigZag)(num);
   }
 
+  function doEncodeProtobuf(bytebuf, message, typeId) {
+    return doEncodeBytesWithLength(bytebuf,encodeProtobuf(message,typeId));
+  }
+
+  function encodeProtobufInstance(root){
+    return function(obj){
+      return root.encode(obj).finish();
+    }
+  }
+
+  function encodeProtobuf(message,typeId){
+    return _.compose(encodeProtobufInstance(WrappedMessage), createWrappedMessage)(message,typeId);
+  }
+
+  function doEncodeQuery(bytebuf,query){
+    return doEncodeBytesWithLength(bytebuf,encodeProtobufInstance(Query.QueryRequest)(query));
+  }
+
+  function createWrappedMessage(message,typeId){
+    var wrappedMessage={};
+    if(_.isNumber(message)){
+      return f.merge(wrappedMessage,{'wrappedDouble':message});
+    }
+    if(_.isString(message)){
+      return f.merge(wrappedMessage,{'wrappedString':message});
+    }
+    if(_.isBoolean(message)){
+      return f.merge(wrappedMessage,{'wrappedBool':message});
+    }
+    if(_.isArrayBuffer(message)){
+      return f.merge(wrappedMessage,{'wrappedBytes':message});
+    }
+    if(f.existy(message.$type)){
+      var encodedMessage = encodeProtobufInstance(message.$type)(message);
+      var messageTypeId = typeId(message.$type.fullName);
+      return f.merge(wrappedMessage,{'wrappedMessage':encodedMessage},{'wrappedTypeId':messageTypeId});
+    }
+    throw new Error("Provide valid data types.");
+  }
+
   function zigZag(num) {
     return (num << 1) ^ (num >> 31);
   }
@@ -90,8 +142,8 @@
   var nullCheck = f.validator('must not be null', f.existy);
   var number = f.validator('must be a number', _.isNumber);
   var positiveOrZero = f.validator('must be >= 0', f.greaterThan(-1));
-  var intTooBig = f.validator('must be less than 2^31', f.lessThan(Math.pow(2, 31)));
-  var shortTooBig = f.validator('must be less than 2^15', f.lessThan(Math.pow(2, 15)));
+  var intTooBig = f.validator('must be less than 2^32', f.lessThan(Math.pow(2, 32)));
+  var shortTooBig = f.validator('must be less than 2^16', f.lessThan(Math.pow(2, 16)));
   var longTooBig = f.validator('must be less than 2^53 (javascript safe integer limitation)',
                                f.lessThan(Math.pow(2, 53)));
   var stringOrNullCheck = f.validator('must be a String or null', stringOrNull);
@@ -124,6 +176,10 @@
     return f.partial1(f.condition1(nullCheck), uncheckedWriteBytes(bytebuf));
   }
 
+  function checkedWriteBytesWithLength(bytebuf) {
+    return f.partial1(f.condition1(nullCheck), uncheckedWriteBytesWithLength(bytebuf));
+  }
+
   function checkedWriteSignedInt(bytebuf) {
     return f.partial1(f.condition1(number, intTooBig), uncheckedWriteVNum(bytebuf));
   }
@@ -209,6 +265,19 @@
     }
   }
 
+  function uncheckedWriteBytesWithLength(bytebuf) {
+    return function(bytes) {
+      var buffNumBytes = f.existy(bytes) ? Buffer.byteLength(bytes) : 0;
+      var offsetAfterBytes = doEncodeVInt(bytebuf, buffNumBytes);
+      if (buffNumBytes > 0) {
+        bytebuf = bytebufOverflowProtect(bytebuf, bytes.length);
+        var targetStart = bytebuf.offset;
+        bytes.copy(bytebuf.buf, targetStart);
+      }
+      return targetStart + buffNumBytes;
+    }
+  }
+
   function doDecodeUByte(bytebuf) {
     return uncheckedReadUByte(bytebuf)();
   }
@@ -253,6 +322,68 @@
     return uncheckedReadShort(bytebuf)();
   }
 
+  function doDecodeProtobuf(bytebuf,protostreamTypename,root){
+    var wrappedObject = _.compose(decodeProtobufMessage(WrappedMessage),trimBytebuf)(bytebuf);
+    return unwrapWrappedMessage(wrappedObject,protostreamTypename,root);
+  }
+
+  function unwrapWrappedMessage(wrappedObject,protostreamTypename,root){
+    switch(true){
+      case _.has(wrappedObject,'wrappedDouble'):
+        return wrappedObject.wrappedDouble;
+      case _.has(wrappedObject,'wrappedString'):
+        return wrappedObject.wrappedString;
+      case _.has(wrappedObject,'wrappedBool'):
+        return wrappedObject.wrappedBool;
+      case _.has(wrappedObject,'wrappedBytes'):
+        return wrappedObject.wrappedBytes;
+      case _.has(wrappedObject,'wrappedMessage'):
+        var messageBytes= wrappedObject.wrappedMessage;
+        var protobufRoot = findRootByTypeId(protostreamTypename,root)(wrappedObject.wrappedTypeId);
+        return decodeProtobufMessage(protobufRoot)(messageBytes);
+    }
+  }
+
+  function decodeProtobufMessage(root){
+    return function(bytebuf){
+      return root.decode(bytebuf);
+    }
+  }
+
+  function findRootByTypeId(protostreamTypename,root){
+    return function(wrappedTypeId){
+      return _.compose(root,protostreamTypename)(wrappedTypeId);
+    } 
+  }
+
+  function trimBytebuf(bytebuf,length){
+    if(!f.existy(length)) length = doDecodeVInt(bytebuf);
+    var retBuf = bytebuf.buf.slice(bytebuf.offset, bytebuf.offset + length);
+    bytebuf.offset += length;
+    return retBuf;
+  }
+
+  function doDecodeQuery(bytebuf,protostreamTypename,root){
+    var queryResponse = decodeProtobufMessage(Query.QueryResponse)(trimBytebuf(bytebuf));
+    var queryResults = queryResponse.results;
+    var projectionSize = queryResponse.projectionSize;
+    return f.greaterThan(0)(projectionSize) ? unwrapQueryWithProj(queryResults,projectionSize) :  unwrapQueryWithoutProj(queryResults,protostreamTypename,root);
+  }
+
+  function decodeWrappedBytes(result,protostreamTypename,root){
+    return _.compose(f.curry3(unwrapWrappedMessage)(root)(protostreamTypename),decodeProtobufMessage(WrappedMessage))(result.wrappedBytes);
+  }
+
+  function unwrapQueryWithoutProj(queryResults,protostreamTypeName,root){
+    return queryResults.map(f.curry3(decodeWrappedBytes)(root)(protostreamTypeName));
+  }
+
+  function unwrapQueryWithProj(queryResults,projectionSize){
+    return _.reduce(queryResults,function(acc,cur,i){
+      return ((i%projectionSize) ? acc[acc.length-1].push(_.values(cur)[0]) : acc.push([_.values(cur)[0]])) && acc;
+    },[]);
+  }
+
   function uncheckedReadUByte(bytebuf) {
     return function() {
       if (1 > bytebuf.buf.length - bytebuf.offset) {
@@ -346,4 +477,24 @@
     }
   }
 
+  var WrappedMessage = (function() {
+    var root=protobuf.loadSync(path.join(__dirname+'/protostream/message-wrapping.proto'));
+
+    var wrappedMessage = root.lookupType('org.infinispan.protostream.WrappedMessage');
+
+    return wrappedMessage;
+  }());
+
+  var Query = (function() {
+    var root=protobuf.loadSync(path.join(__dirname+'/protostream/query.proto'));
+    protobuf.loadSync(path.join(__dirname+'/protostream/message-wrapping.proto'),root); //loaded the wrappedMessage.proto to the root
+    var QueryRequest = root.lookupType('org.infinispan.query.remote.client.QueryRequest');
+    var QueryResponse = root.lookupType('org.infinispan.query.remote.client.QueryResponse');
+
+    return {
+      QueryRequest,
+      QueryResponse
+    };
+  }());
+
 }.call(this));