Recent changes to JavaKnowledgeContainers

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Mon, 25 Jun 2018 19:01:01 -0000

--- v17
+++ v18
@@ -58,7 +58,7 @@

 ### 1.1.2 Double

-Location: `com.madara.containers.Double` 

+Location: `ai.madara.knowledge.containers.Double` 

 Documentation: [Double](http://madara.sourceforge.net/docs/java/com/madara/containers/Double.html)

 Double is a container that provides interfaces for setting and getting a double value from the Knowledge Base.
@@ -90,7 +90,7 @@

 ### 1.1.3 String

-Location: `com.madara.containers.String` 

+Location: `ai.madara.knowledge.containers.String` 

 Documentation: [String](http://madara.sourceforge.net/docs/cpp/d5/ded/classMadara_1_1Knowledge__Engine_1_1Containers_1_1String.html)

 String is a container that provides interfaces for setting and getting a string value from the Knowledge Base.
@@ -130,7 +130,7 @@

 ### 1.2.1 Integer Vector/Array

-Location: `com.madara.containers.IntegerVector` 

+Location: `ai.madara.knowledge.containers.IntegerVector` 

 Documentation: [IntegerVector](http://madara.sourceforge.net/docs/java/com/madara/containers/IntegerVector.html)

 `IntegerVector` is a container that provides interfaces for setting and getting an integer value from the Knowledge Base.

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Mon, 25 Jun 2018 19:00:15 -0000

--- v16
+++ v17
@@ -26,15 +26,15 @@

 ### 1.1.1 Integer

-Location: `com.madara.containers.Integer` 

+Location: `ai.madara.knowledge.containers.Integer` 

 Documentation: [Integer](http://madara.sourceforge.net/docs/java/com/madara/containers/Integer.html)

 Integer is a container that provides interfaces for setting and getting an integer value from the Knowledge Base.

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.Integer;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.Integer;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -65,8 +65,8 @@

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.Double;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.Double;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -97,8 +97,8 @@

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.String;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.String;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -137,8 +137,8 @@

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.IntegerVector;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.IntegerVector;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -170,15 +170,15 @@

 ### 1.2.2 Double Vector/Array

-Location: `com.madara.containers.DoubleVector` 

+Location: `ai.madara.knowledge.containers.DoubleVector` 

 Documentation: [DoubleVector](http://madara.sourceforge.net/docs/java/com/madara/containers/IntegerVector.html)

 `Double_Vector` is a container that provides interfaces for setting and getting an array of double values within the Knowledge Base.

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.DoubleVector;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.DoubleVector;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -211,15 +211,15 @@

 ### 1.2.3 String Vector/Array

-Location: `com.madara.containers.StringVector` 

+Location: `ai.madara.knowledge.containers.StringVector` 

 Documentation: [StringVector](http://madara.sourceforge.net/docs/java/com/madara/containers/StringVector.html)

 `StringVector`, also known as `String_Array`, is a container that provides interfaces for setting and getting an array of string values within the Knowledge Base.

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.StringVector;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.StringVector;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -255,15 +255,15 @@

 Map containers are facades into string-keyed maps of variable locations within the Knowledge Base. Unlike with instance variables, the name that is set for a map container is the prefix for variable locations instead of an actual variable name, and access times are O(log m), where m is the number of items existing in the Map container.

-Location: `com.madara.containers.Map` 

+Location: `ai.madara.knowledge.containers.Map` 

 Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/Map.html)

 The Map class is one of the most versatile container classes available in MADARA. This class is likely to prove invaluable to developers wanting to emulate classes within the knowledge base.

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.Map;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.Map;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a container that points inside it
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -298,7 +298,7 @@

 Flexible Maps are abstractions intended to support multi-dimensional arrays and maps. These containers provide both integer-based index and string-based accesses. These functions return other Flexible Maps which can either be set to an arbitrary value (such as an integer, string, double, byte buffer, etc.) or subindexed with integers or strings.

-Location: `com.madara.containers.FlexMap` 

+Location: `ai.madara.knowledge.containers.FlexMap` 

 Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/FlexMap.html)

 `FlexMap` replaces the old `VectorN` class which was less intuitive and useful. `FlexMap` is O(1) for subindexing (e.g., [1][2]) and only incurs an O(log n), with n being the number of keys in the knowledge base, lookup on the first access of an element with an accessor or mutator function (e.g. `to_string()` or setting the value explicitly). FlexMap essentially always assumes an index is not a variable lookup until you are setting or getting a value explicitly. The keys function is an O(n) operation that must look through all keys in the Knowledge_Base to find all versions with the prefix set in constructor or set_name function.
@@ -309,9 +309,9 @@

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.FlexMap;
-import com.madara.containers.String;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.FlexMap;
+import ai.madara.knowledge.containers.String;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a multi-dimensional array
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -348,16 +348,16 @@

 Counters are abstractions intended to support aggregate counters across multiple participating agents. Counters provide a solution to the problem of the many writers problem for single variable increments/decrements. What a Counter does under the hood is give each agent a copy of the variable, and the agent only increments/decrements/sets their versions of the variable. When another agent wants to know, the aggregate count, they call `toInteger()` or `toRecord()`.

-Location: `com.madara.containers.Counter` 

+Location: `ai.madara.knowledge.containers.Counter` 

 Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/Counter.html)

 Updating the Counter takes O(1) time. Retrieving a value from the Counter requires O(N) time, where N is the number of agents participating in the counting operation.

 ~~~~~~
 // import containers and KnowledgeBase
-import com.madara.containers.FlexMap;
-import com.madara.containers.String;
-import com.madara.KnowledgeBase;
+import ai.madara.knowledge.containers.FlexMap;
+import ai.madara.knowledge.containers.String;
+import ai.madara.knowledge.KnowledgeBase;

 // create a knowledge base and make a multi-dimensional array
 KnowledgeBase knowledge = new KnowledgeBase();
@@ -395,10 +395,10 @@
 To showcase this concept, we'll use a complete program that sends a profile over multicast.

 ~~~~~~
-import com.madara.KnowledgeBase;
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.TransportType;
-import com.madara.containers.Map;
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.knowledge.transport.QoSTransportSettings;
+import ai.madara.knowledge.transport.TransportType;
+import ai.madara.knowledge.containers.Map;

 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
@@ -449,10 +449,10 @@
 In the next example, we create a function called `setProfile` that is called from an evaluate statement within the main function.

 ~~~~~~import com.madara.KnowledgeBase;
-import com.madara.MadaraFunction;
-import com.madara.KnowledgeRecord;
-import com.madara.KnowledgeList;
-import com.madara.Variables;
+import ai.madara.knowledge.MadaraFunction;
+import ai.madara.knowledge.KnowledgeRecord;
+import ai.madara.knowledge.KnowledgeList;
+import ai.madara.knowledge.Variables;
 import someGpsModule;

 private class SetProfile extends MadaraFunction

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Sat, 15 Aug 2015 14:18:24 -0000

--- v15
+++ v16
@@ -365,7 +365,8 @@

 entries.setName(knowledge, "entries");

-// resize our entries counter to have 2 variables (2 agents), with our id as 0 (the other agent would be 1)
+// resize our entries counter to have 2 variables (2 agents),
+// with our id as 0 (the other agent would be 1)
 entries.resize(0, 2);

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Sat, 15 Aug 2015 14:17:35 -0000

--- v14
+++ v15
@@ -365,6 +365,10 @@

 entries.setName(knowledge, "entries");

+// resize our entries counter to have 2 variables (2 agents), with our id as 0 (the other agent would be 1)
+entries.resize(0, 2);
+
+
 // add 3 to the number of entries that you are maintaining
 entries.inc();
 entries.inc(2);

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Sat, 15 Aug 2015 14:09:53 -0000

--- v13
+++ v14
@@ -363,7 +363,6 @@
 KnowledgeBase knowledge = new KnowledgeBase();
 Counter entries = new Counter();

-
 entries.setName(knowledge, "entries");

 // add 3 to the number of entries that you are maintaining

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Sat, 15 Aug 2015 14:09:32 -0000

--- v12
+++ v13
@@ -344,6 +344,38 @@

 ----

+## 1.5 Counter
+
+Counters are abstractions intended to support aggregate counters across multiple participating agents. Counters provide a solution to the problem of the many writers problem for single variable increments/decrements. What a Counter does under the hood is give each agent a copy of the variable, and the agent only increments/decrements/sets their versions of the variable. When another agent wants to know, the aggregate count, they call `toInteger()` or `toRecord()`.
+
+Location: `com.madara.containers.Counter` 

+Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/Counter.html)
+
+Updating the Counter takes O(1) time. Retrieving a value from the Counter requires O(N) time, where N is the number of agents participating in the counting operation.
+
+~~~~~~
+// import containers and KnowledgeBase
+import com.madara.containers.FlexMap;
+import com.madara.containers.String;
+import com.madara.KnowledgeBase;
+
+// create a knowledge base and make a multi-dimensional array
+KnowledgeBase knowledge = new KnowledgeBase();
+Counter entries = new Counter();
+
+
+entries.setName(knowledge, "entries");
+
+// add 3 to the number of entries that you are maintaining
+entries.inc();
+entries.inc(2);
+
+// other agents across the network may have updated their entry in "entries"
+System.out.println ("Total entries in network is : " + entries.toString());
+~~~~~~
+
+----
+
 # 2. Interaction with the Transport Layer 

 When creating containers, each constructor supports a `Madara::Knowledge_Engine::Knowledge_Update_Settings` instance that provides control over the updating and retrieving of variables from the context. However, no function in the container classes directly interacts with the transport layer.

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Sat, 15 Aug 2015 13:41:39 -0000

--- v11
+++ v12
@@ -340,6 +340,8 @@

 ~~~~~~

+The above example shows the flexibility of using the FlexMap, but in reality, you will want to call `free()` on each return value of `get()` on a FlexMap. We do provide `finalize` overrides with each container ported to Java, but Java does not guarantee that such methods will ever be called. To make sure you free the underlying C++ memory, it is best practice to call `free()` explicitly when you are done using a FlexMap.
+
 ----

 # 2. Interaction with the Transport Layer

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Wed, 17 Jun 2015 17:36:28 -0000

--- v10
+++ v11
@@ -296,7 +296,7 @@

 ## 1.4 Flexible Map

-Flexible Maps are abstractions intended to support multi-dimensional arrays and maps. These containers provide both integer-based index and string-based accesses. These functions return other Flexible Map which can either be set to an arbitrary value (such as an integer, string, double, byte buffer, etc.) or subindexed with integers or strings.
+Flexible Maps are abstractions intended to support multi-dimensional arrays and maps. These containers provide both integer-based index and string-based accesses. These functions return other Flexible Maps which can either be set to an arbitrary value (such as an integer, string, double, byte buffer, etc.) or subindexed with integers or strings.

 Location: `com.madara.containers.FlexMap` 

 Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/FlexMap.html)

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Wed, 17 Jun 2015 17:34:20 -0000

--- v9
+++ v10
@@ -251,54 +251,7 @@

 ----

-### 1.2.4 Dynamically-typed Vector/Array
-
-Location: `com.madara.containers.Vector.h` 

-Documentation: [Vector](http://madara.sourceforge.net/docs/java/com/madara/containers/Vector.html)
-
-`Vector` is a container that provides interfaces for setting and getting an array of multi-typed values within the Knowledge Base.
-
-~~~~~~
-// import containers and KnowledgeBase
-import com.madara.containers.VectorVector;
-import com.madara.KnowledgeBase;
-
-// create a knowledge base and make a container that points inside it
-KnowledgeBase knowledge = new KnowledgeBase();
-Vector myArray myArray = new Vector();
-myArray.setName(knowledge, ".array", 10);
-
-// the array contains five characters from Snow White and their ages
-myArray.set(0, "Snow White");
-myArray.set(1, "Doc");
-myArray.set(2, "Dopey");
-myArray.set(3, "Bashful");
-myArray.set(4, "Grumpy");
-myArray.set(5, 18);
-myArray.set(6, 70);
-myArray.set(7, 74);
-myArray.set(8, 72);
-myArray.set(9, 68);
-
-...
-
-// print out the people and their ages
-for (unsigned int i 0; i < 5; ++i)
-  System.out.println(myArray.get(i).toString() + "'s age is " + myArray.get(i + 5));
-
-/**
- * in a persistent application, we would actually want to free() whatever is returned by
- * myArray.get(i + 5). Otherwise, you'll have a small memory leak.
- **/
-
-// free the C++ resources
-myArray.free();
-knowledge.free();
-~~~~~~
-
-----
-
-## 1.4 Maps
+## 1.3 Maps

 Map containers are facades into string-keyed maps of variable locations within the Knowledge Base. Unlike with instance variables, the name that is set for a map container is the prefix for variable locations instead of an actual variable name, and access times are O(log m), where m is the number of items existing in the Map container.

@@ -337,6 +290,54 @@
 // free the C++ resources
 map.free();
 knowledge.free();
+~~~~~~
+
+----
+
+## 1.4 Flexible Map
+
+Flexible Maps are abstractions intended to support multi-dimensional arrays and maps. These containers provide both integer-based index and string-based accesses. These functions return other Flexible Map which can either be set to an arbitrary value (such as an integer, string, double, byte buffer, etc.) or subindexed with integers or strings.
+
+Location: `com.madara.containers.FlexMap` 

+Documentation: [Map](http://madara.sourceforge.net/docs/java/com/madara/containers/FlexMap.html)
+
+`FlexMap` replaces the old `VectorN` class which was less intuitive and useful. `FlexMap` is O(1) for subindexing (e.g., [1][2]) and only incurs an O(log n), with n being the number of keys in the knowledge base, lookup on the first access of an element with an accessor or mutator function (e.g. `to_string()` or setting the value explicitly). FlexMap essentially always assumes an index is not a variable lookup until you are setting or getting a value explicitly. The keys function is an O(n) operation that must look through all keys in the Knowledge_Base to find all versions with the prefix set in constructor or set_name function.
+
+Though the subindexing is O(1), developers should keep in mind that each index is a concatenation of the container name with a delimiter (by default '.') and the index, which is essentially 2 concatenation operations.
+
+`FlexMap` includes to*Container operations that can convert the `FlexMap` into any supported container for fast O(1) changes later to String, Integer, Double, etc.
+
+~~~~~~
+// import containers and KnowledgeBase
+import com.madara.containers.FlexMap;
+import com.madara.containers.String;
+import com.madara.KnowledgeBase;
+
+// create a knowledge base and make a multi-dimensional array
+KnowledgeBase knowledge = new KnowledgeBase();
+FlexMap map = new FlexMap();
+String cityName;
+
+map.setName(knowledge, "cities");
+
+// set location cities.1.2.3.4.name to "St. Louis"
+map.get(1).get(2).get(3).get(4).get("name").set("St. Louis");
+
+// set location cities.4.2.3.4.name to "San Francisco"
+map.get(4).get(2).get(3).get(4).get("name").set("San Francisco");
+
+// output the value at [1][2][3][4]
+System.out.println ("First town is " + map.get(1).get(2).get(3).get(4).get("name").toString());
+
+// output the value at [4][2][3][4]
+System.out.println ("Second town is " + map.get(4).get(2).get(3).get(4).get("name").toString());
+
+// FlexMap can create containers to its elements for faster access
+cityName = map.get(4).get(2).get(3).get(4).get("name").toStringContainer ();
+cityName.set("Ontario");
+
+System.out.println ("Second town is " + cityName.toString());
+
 ~~~~~~

 ----

JavaKnowledgeContainers modified by James Edmondson

James Edmondson — Wed, 05 Nov 2014 07:51:53 -0000

--- v8
+++ v9
@@ -48,6 +48,10 @@

 // print the value to stdout
 System.out.println ("My id is " + myId.get());
+
+// free the C++ resources
+myId.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -76,6 +80,10 @@

 // print the value to stdout
 System.out.println ("My funds available are " + funds.get());
+
+// free the C++ resources
+funds.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -106,6 +114,10 @@

 // print the value to stdout
 System.out.println ("My name is " + name.get());
+
+// free the C++ resources
+name.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -148,6 +160,10 @@
 System.out.println("myArray.get(0) is " + myArray.get(0));
 System.out.println("myArray.get(1) is " + myArray.get(1));
 System.out.println("myArray.get(5) is " + myArray.get(5));
+
+// free the C++ resources
+myArray.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -184,6 +200,10 @@
 System.out.println("myArray.get(0) is " + myArray.get(0));
 System.out.println("myArray.get(1) is " + myArray.get(1));
 System.out.println("myArray.get(5) is " + myArray.get(5));
+
+// free the C++ resources
+myArray.free();
+knowledge.free();
 ~~~~~~

@@ -223,6 +243,10 @@
 // print out all elements of the array
 for (unsigned int i 0; i < 10; ++i)
   System.out.println("array.get(" + i + ") is " + myArray.get(i));
+
+// free the C++ resources
+myArray.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -261,6 +285,15 @@
 // print out the people and their ages
 for (unsigned int i 0; i < 5; ++i)
   System.out.println(myArray.get(i).toString() + "'s age is " + myArray.get(i + 5));
+
+/**
+ * in a persistent application, we would actually want to free() whatever is returned by
+ * myArray.get(i + 5). Otherwise, you'll have a small memory leak.
+ **/
+
+// free the C++ resources
+myArray.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -295,6 +328,15 @@
 System.out.println("Age: " + map.get("age"));
 System.out.println("funds: " + map.get("funds"));
 System.out.println("Photo: " + map.get("photo1"));
+
+/**
+ * in a persistent application, we would actually want to free() whatever is returned by
+ * map.get(...). Otherwise, you'll have a small memory leak.
+ **/
+
+// free the C++ resources
+map.free();
+knowledge.free();
 ~~~~~~

 ----
@@ -348,6 +390,11 @@
  * profile.1.funds, and profile.1.photo1
  */ 
 knowledge.sendModifieds();
+
+// free the C++ resources
+map.free();
+knowledge.free();
+settings.free();
 ~~~~~~

 ----
@@ -385,6 +432,8 @@
     profile.set("funds", 300.50);
     profile.set("photo1", "/images/profile/1/headshot.jpg");  

+    profile.free();
+    
     return result;
   }
 }
@@ -406,7 +455,11 @@
 knowledge.evaluate("setProfile()");

 // sleep for a few seconds
-knowledge.evaluate("#sleep(3)");                                                                             
+knowledge.evaluate("#sleep(3)");
+
+// free the C++ resources
+knowledge.free();
+settings.free();                                                                             
 ~~~~~~

 ----