Recent changes to JavaInteractingWithTheTransport

JavaInteractingWithTheTransport modified by James Edmondson

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

--- v14
+++ v15
@@ -5,7 +5,7 @@

 # MADARA Transport Layer

-The main entry point into the MADARA transport layer is the [QoSTransportSettings](http://madara.sourceforge.net/docs/java/com/madara/transport/QoSTransportSettings.html) class. The QoSTransportSettings class contains dozens of network-specific settings that govern basic configuration, quality-of-service, and filtering.
+The main entry point into the MADARA transport layer is the [QoSTransportSettings](https://static.javadoc.io/ai.madara/madara/3.2.0/ai/madara/transport/QoSTransportSettings.html) class. The QoSTransportSettings class contains dozens of network-specific settings that govern basic configuration, quality-of-service, and filtering.

 

@@ -28,9 +28,9 @@
 _Example of UDP transport constructor example_

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

 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings();
@@ -52,10 +52,10 @@
 If the madara_registry goes offline, the agents that have talked with the madara_registry before will continue to use the last hosts they knew of. Whenever a madara_registry comes back online (e.g., when you restart it), everything should work without any issues.

 ~~~~~~
-import com.madara.KnowledgeBase;
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.TransportType;
-import com.madara.filters.EndpointClear;
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+import ai.madara.filters.EndpointClear;

 //create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings();
@@ -79,9 +79,9 @@
 _Example of multicast transport constructor_ ([Multicast IP range](http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml))

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

 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
@@ -99,9 +99,9 @@
 _Example of broadcast transport constructor_

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

 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
@@ -129,6 +129,10 @@
 _Example of sending a packet with a rebroadcast ttl of 3_

 ~~~~~~
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+
 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
 settings.setHosts(new String[]{"239.255.0.1:4150"});
@@ -146,6 +150,10 @@
 _Example of enabling participation in rebroadcasts_

 ~~~~~~
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+
 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
 settings.setHosts(new String[]{"239.255.0.1:4150"});
@@ -177,6 +185,10 @@
 _Example of enforcing a send bandwidth limit_

 ~~~~~~
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+
 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
 settings.setHosts(new String[]{"239.255.0.1:4150"});
@@ -193,6 +205,10 @@
 _Example of enforcing a total bandwidth limit_

 ~~~~~~
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+
 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
 settings.setHosts(new String[]{"239.255.0.1:4150"});
@@ -213,6 +229,10 @@
 _Example of enforcing a transport latency deadline_

 ~~~~~~
+import ai.madara.knowledge.KnowledgeBase;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.TransportType;
+
 //Create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings ();
 settings.setHosts(new String[]{"239.255.0.1:4150"});
@@ -236,7 +256,7 @@

 * args`[0]`: The knowledge record that the filter is acting upon
 * args`[1]`: The name of the knowledge record, if applicable ("" if unnamed, but this should never happen)
-* args`[2]`: The type of operation calling the filter (integer valued). Valid types are: `Madara::Transport::Transport_Context::IDLE_OPERATION` (should never see), `Madara::Transport::Transport_Context::SENDING_OPERATION` (transport is trying to send the record), `Madara::Transport::Transport_Context::RECEIVING_OPERATION` (transport has received the record and is ready to apply the update), `Madara::Transport::Transport_Context::REBROADCASTING_OPERATION` (transport is trying to rebroadcast the record -- only happens if rebroadcast is enabled in Transport Settings)
+* args`[2]`: The type of operation calling the filter (integer valued). Valid types are: `IDLE_OPERATION` (should never see), `SENDING_OPERATION` (transport is trying to send the record), `RECEIVING_OPERATION` (transport has received the record and is ready to apply the update), `REBROADCASTING_OPERATION` (transport is trying to rebroadcast the record -- only happens if rebroadcast is enabled in Transport Settings)
 * args`[3]`: Bandwidth used while sending through this transport, measured in bytes per second.
 * args`[4]`: Bandwidth used while receiving from this transport, measured in bytes per second.
 * args`[5]`: Message timestamp (when the message was originally sent, in seconds)
@@ -246,7 +266,7 @@

 The filter can add data to the payload by pushing a variable name (string) followed by a value, which can be a double, string, integer, byte array, or array of integers or doubles, just as you would do with a set operation. This can be useful if other reasoners in the network are expecting additional meta data for the update (which they are free to strip out or ignore in a receive filter, if they don't need the information).

-The filter can also access any variable in the [Knowledge_Base](http://madara.sourceforge.net/docs/java/com/madara/KnowledgeBase.html) through the [Variables](http://madara.sourceforge.net/docs/java/com/madara/Variables.html) facade. With the arguments and variables interfaces, developers can respond to transport events in highly dynamic and extensible ways.
+The filter can also access any variable in the [Knowledge_Base](https://static.javadoc.io/ai.madara/madara/3.2.0/ai/madara/knowledge/KnowledgeBase.html) through the [Variables](https://static.javadoc.io/ai.madara/madara/3.2.0/ai/madara/knowledge/Variables.html) facade. With the arguments and variables interfaces, developers can respond to transport events in highly dynamic and extensible ways.

 ----

@@ -259,11 +279,11 @@
 _Example of enforcing a send bandwidth limit via filtering_

 ~~~~~~
-import com.madara.KnowledgeRecord;
-import com.madara.Variables;
-import com.madara.KnowledgeList;
-import com.gams.transport.filters.RecordFilter;
-import com.madara.KnowledgeType;
+import ai.madara.knowledge.KnowledgeRecord;
+import ai.madara.knowledge.Variables;
+import ai.madara.knowledge.KnowledgeList;
+import ai.madara.transport.filters.RecordFilter;
+import ai.madara.knowledge.KnowledgeType;

 public class SendBandwidthLimit implements RecordFilter
 {
@@ -312,10 +332,10 @@
 _Example of enforcing a network latency deadline via filtering_

 ~~~~~~
-import com.madara.KnowledgeRecord;
-import com.madara.Variables;
-import com.madara.KnowledgeList;
-import com.gams.transport.filters.RecordFilter;
+import ai.madara.knowledge.KnowledgeRecord;
+import ai.madara.knowledge.Variables;
+import ai.madara.knowledge.KnowledgeList;
+import ai.madara.transport.filters.RecordFilter;

 public class DeadlineEnforcement implements RecordFilter
 {
@@ -364,10 +384,10 @@
 _Example of shaping a payload before it gets sent out_

 ~~~~~~
-import com.madara.KnowledgeRecord;
-import com.madara.Variables;
-import com.madara.KnowledgeList;
-import com.gams.transport.filters.RecordFilter;
+import ai.madara.knowledge.KnowledgeRecord;
+import ai.madara.knowledge.Variables;
+import ai.madara.knowledge.KnowledgeList;
+import ai.madara.transport.filters.RecordFilter;
 import java.util.StringBuffer;

 public class AddItemTag implements RecordFilter
@@ -419,11 +439,11 @@
 We will highlight the utility and power of aggregate filters with a simple example which adds the id of the current process as metadata to every message sent. It then strips the id from the aggregate before applying the information to the knowledge base.

 ~~~~~~
-import com.madara.KnowledgeRecord;
-import com.madara.Variables;
-import com.madara.KnowledgeList;
-import com.madara.EvalSettings;
-import com.gams.transport.filters.RecordFilter;
+import ai.madara.knowledge.KnowledgeRecord;
+import ai.madara.knowledge.Variables;
+import ai.madara.knowledge.KnowledgeList;
+import ai.madara.knowledge.EvalSettings;
+import ai.madara.transport.filters.RecordFilter;
 import java.util.StringBuffer;

 public class AddOrEraseId implements RecordFilter
@@ -484,7 +504,7 @@
 _Example of adding peers to trusted list_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
+import ai.madara.transport.QoSTransportSettings;

 // only trust the agents "agent2" and "agent3"
 QoSTransportSettings settings = new QoSTransportSettings();
@@ -500,7 +520,7 @@
 _Example of adding peers to banned list_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
+import ai.madara.transport.QoSTransportSettings;

 // Do not trust "agent1"
 QoSTransportSettings settings = new QoSTransportSettings();
@@ -525,8 +545,8 @@
 _Example of setting a deterministic non-bursty packet drop policy_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.DropType;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.DropType;

 QoSTransportSettings settings = new QoSTransportSettings();
 /**
@@ -544,8 +564,8 @@
 _Example of setting a deterministic bursty packet drop policy_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.DropType;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.DropType;

 QoSTransportSettings settings = new QoSTransportSettings();
 /**
@@ -569,8 +589,8 @@
 _Example of setting a deterministic non-bursty packet drop policy_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.DropType;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.DropType;

 QoSTransportSettings settings = new QoSTransportSettings();

@@ -588,8 +608,8 @@
 _Example of setting a deterministic bursty packet drop policy_

 ~~~~~~
-import com.madara.transport.QoSTransportSettings;
-import com.madara.transport.DropType;
+import ai.madara.transport.QoSTransportSettings;
+import ai.madara.transport.DropType;

 QoSTransportSettings settings = new QoSTransportSettings();
 /**
@@ -604,7 +624,7 @@

 # More Information

-The Java module is fully documented with standard java documentation. Please use the API at [JavaDocs](http://madara.sourceforge.net/docs/java) or tell your editor of choice to load source files from the Git repository.
+The Java module is fully documented with standard java documentation. Please use the API at [JavaDocs](https://www.javadoc.io/doc/ai.madara/madara) or tell your editor of choice to load source files from the Git repository.

 ----
 Java Guide Series

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Fri, 30 Oct 2015 17:50:59 -0000

--- v13
+++ v14
@@ -60,7 +60,7 @@
 //create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings();

-// assume a registry server on the local host at port 40000
+//assume a registry server on the local host at port 40000
 settings.setHosts(new String[]{"localhost:40000"});
 settings.setType(TransportType.REGISTRY_CLIENT);

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Fri, 30 Oct 2015 17:50:33 -0000

--- v12
+++ v13
@@ -59,7 +59,9 @@

 //create transport settings for a multicast transport
 QoSTransportSettings settings = new QoSTransportSettings();
-settings.setHosts(new String[]{"localhost:40000", "localhost:40001});
+
+// assume a registry server on the local host at port 40000
+settings.setHosts(new String[]{"localhost:40000"});
 settings.setType(TransportType.REGISTRY_CLIENT);

 //create endpoint clear filter, which will tidy up registry updates

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Wed, 28 Oct 2015 20:41:00 -0000

--- v11
+++ v12
@@ -36,6 +36,35 @@
 QoSTransportSettings settings = new QoSTransportSettings();
 settings.setHosts(new String[]{"localhost:40000", "localhost:40001});
 settings.setType(TransportType.UDP_TRANSPORT);
+
+//create a knowledge base with the multicast transport settings
+KnowledgeBase knowledge = new KnowledgeBase("", settings);
+
+//send all agents listening on this multicast address the knowledge
+//that all agents are currently ready
+knowledge.evaluate("all_agents_ready = 1");
+~~~~~~
+
+_Example of UDP registry transport constructor example_
+
+UDP Registry is a special UDP transport that dynamically recognizes new and leaving hosts after deployment. To use the UDP Registry transport, you need to have a madara_registry running (located at $MADARA_ROOT/bin/madara_registry). This UDP registry should work over 3G, 4G, and from behind NATs as long as the NAT maintains the UDP host:port for the madara_registry binding.
+
+If the madara_registry goes offline, the agents that have talked with the madara_registry before will continue to use the last hosts they knew of. Whenever a madara_registry comes back online (e.g., when you restart it), everything should work without any issues.
+
+~~~~~~
+import com.madara.KnowledgeBase;
+import com.madara.transport.QoSTransportSettings;
+import com.madara.transport.TransportType;
+import com.madara.filters.EndpointClear;
+
+//create transport settings for a multicast transport
+QoSTransportSettings settings = new QoSTransportSettings();
+settings.setHosts(new String[]{"localhost:40000", "localhost:40001});
+settings.setType(TransportType.REGISTRY_CLIENT);
+
+//create endpoint clear filter, which will tidy up registry updates
+EndpointClear filter = new EndpointClear();
+filter.addReceiveFilterTo(settings);

 //create a knowledge base with the multicast transport settings
 KnowledgeBase knowledge = new KnowledgeBase("", settings);

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 24 Mar 2015 18:25:31 -0000

--- v10
+++ v11
@@ -109,7 +109,7 @@
 Madara::Transport::QoS_Transport_Settings settings;
 settings.setRebroadcastTtl(3);

-Madara::Knowledge_Engine::Knowledge_Base knowledge ("", settings);
+KnowledgeBase knowledge = new KnowledgeBase("", settings);
 ~~~~~~

 _Example of enabling participation in rebroadcasts_
@@ -122,7 +122,7 @@
 settings.setRebroadcastTtl(2);
 settings.enableParticipantTtl(1);

-Madara::Knowledge_Engine::Knowledge_Base knowledge ("", settings);
+KnowledgeBase knowledge = new KnowledgeBase("", settings);
 ~~~~~~

 ----

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 04 Nov 2014 02:05:19 -0000

--- v9
+++ v10
@@ -1,5 +1,5 @@
 Java Guide Series
-[Architecture](JavaMadaraArchitecture) | [Knowledge Base](JavaInteractingWithTheKnowledgeBase) | [Networking](JavaInteractingWithTheTransport) | [Containers](JavaKnowledgeContainers) | [Threads](JavaWorkingWithThreads) | [Optimizations](JavaOptimizingKaRL)
+[Architecture](JavaMadaraArchitecture) | [Knowledge Base](JavaInteractingWithTheKnowledgeBase) | Networking | [Containers](JavaKnowledgeContainers) | [Threads](JavaWorkingWithThreads)

 ----

@@ -577,4 +577,4 @@

 ----
 Java Guide Series
-[Architecture](JavaMadaraArchitecture) | [Knowledge Base](JavaInteractingWithTheKnowledgeBase) | [Networking](JavaInteractingWithTheTransport) | [Containers](JavaKnowledgeContainers) | [Threads](JavaWorkingWithThreads) | [Optimizations](JavaOptimizingKaRL)
+[Architecture](JavaMadaraArchitecture) | [Knowledge Base](JavaInteractingWithTheKnowledgeBase) | Networking | [Containers](JavaKnowledgeContainers) | [Threads](JavaWorkingWithThreads)

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 04 Nov 2014 00:59:13 -0000

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 04 Nov 2014 00:57:53 -0000

--- v7
+++ v8
@@ -573,7 +573,7 @@

 # More Information

-The Java module is fully documented with standard java documentation. Please use the API at [JavaDocs](http://madara.sourceforge.net/docs/java) or tell your editor of choice to load source files from the SVN repository
+The Java module is fully documented with standard java documentation. Please use the API at [JavaDocs](http://madara.sourceforge.net/docs/java) or tell your editor of choice to load source files from the Git repository.

 ----
 Java Guide Series

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 04 Nov 2014 00:52:16 -0000

JavaInteractingWithTheTransport modified by James Edmondson

James Edmondson — Tue, 04 Nov 2014 00:47:32 -0000

--- v5
+++ v6
@@ -131,7 +131,7 @@

 The MADARA architecture monitors two different types of bandwidth usage: sending and receiving bandwidth. Setting a limit for either of these will serve as a hard limit that does not differentiate between priorities of information. Once a packet is sent, the bandwidth counters are updated, and if the bytes per second rate is higher than the limit you set, all packets will be dropped until the rate dips below the limit. These limiters do not currently look at the size of the packet that is being sent out, so if you are at 99,500 B/s and your limit is 100,000 B/s, it will try to send any next packet (even if it 1MB), update the bandwidth counter, and then not send another packet until you reach 99,500 B/s sent over the past 10s.

-For a more flexible bandwidth option that you can configure, see [https://code.google.com/p/madara/wiki/InteractingWithTheTransport#Bandwidth_Filters Bandwidth Filters].
+For a more flexible bandwidth option that you can configure, see Bandwidth Filters.

 Deadline enforcement is concerned with enforcing latency deadlines between reasoning entitites on the network. Deadline enforcement requires some type of time synchronization protocol between agents in the network, preferably accurate to within a second, for it to be useful to the MADARA entities.

@@ -215,7 +215,7 @@

 The filter can add data to the payload by pushing a variable name (string) followed by a value, which can be a double, string, integer, byte array, or array of integers or doubles, just as you would do with a set operation. This can be useful if other reasoners in the network are expecting additional meta data for the update (which they are free to strip out or ignore in a receive filter, if they don't need the information).

-The filter can also access any variable in the [https://madara.googlecode.com/svn/docs/karl/html/df/d02/classMadara_1_1Knowledge__Engine_1_1Knowledge__Base.html Knowledge_Base] through the [https://madara.googlecode.com/svn/docs/karl/html/da/d07/classMadara_1_1Knowledge__Engine_1_1Variables.html Madara::Knowledge_Engine::Variables] facade. With the arguments and variables interfaces, developers can respond to transport events in highly dynamic and extensible ways.
+The filter can also access any variable in the [Knowledge_Base](http://madara.sourceforge.net/docs/java/com/madara/KnowledgeBase.html) through the [Variables](http://madara.sourceforge.net/docs/java/com/madara/Variables.html) facade. With the arguments and variables interfaces, developers can respond to transport events in highly dynamic and extensible ways.

 ----