Provider system for the message api

build.gradle

@@ -24,9 +24,11 @@ ext {
 }
 
 /** needed to disable Java 8 doclint which throws errors **/
-allprojects {
-    tasks.withType(Javadoc) {
-        options.addStringOption('Xdoclint:none', '-quiet')
+if (JavaVersion.current().isJava8Compatible()) {
+    allprojects {
+        tasks.withType(Javadoc) {
+            options.addStringOption('Xdoclint:none', '-quiet')
+        }
     }
 }
 

gdx-ai/src/com/badlogic/gdx/ai/msg/MessageDispatcher.java

@@ -21,6 +21,7 @@
 import com.badlogic.gdx.utils.IntMap;
 import com.badlogic.gdx.utils.Pool;
 import com.badlogic.gdx.utils.TimeUtils;
+import com.badlogic.gdx.utils.reflect.ClassReflection;
 
 /** The MessageDispatcher is a singleton in charge of the creation, dispatch, and management of telegrams.
  * 
@@ -41,6 +42,8 @@
 
 	private IntMap<Array<Telegraph>> msgListeners = new IntMap<Array<Telegraph>>();
 
+	private IntMap<Array<TelegramProvider>> msgProviders = new IntMap<Array<TelegramProvider>>();
+
 	private long timeGranularity;
 
 	private boolean debugEnabled;
@@ -116,18 +119,51 @@ public void addListener (Telegraph listener, int msg) {
 			msgListeners.put(msg, listeners);
 		}
 		listeners.add(listener);
+		// dispatch messages from registered providers
+		Array<TelegramProvider> providers = msgProviders.get(msg);
+		if (providers != null) {
+			for (int i = 0; i < providers.size; i++) {
+				TelegramProvider provider = providers.get(i);
+				Object info = provider.provideMessageInfo(msg, listener);
+				if (info != null) if (ClassReflection.isInstance(Telegraph.class, provider))
+					dispatchMessage(0, (Telegraph)provider, listener, msg, info);
+				else
+					dispatchMessage(0, null, listener, msg, info);
+			}
+		}
 	}
 
 	/** Registers a listener for a selection of message types. Messages without an explicit receiver are broadcasted to all its
 	 * registered listeners.
-	 * 
+	 *
 	 * @param listener the listener to add
 	 * @param msgs the message codes */
 	public void addListeners (Telegraph listener, int... msgs) {
 		for (int msg : msgs)
 			addListener(listener, msg);
 	}
 
+	/** Registers a provider for the specified message code.
+	 * @param msg the message code
+	 * @param provider the provider to add */
+	public void addProvider (TelegramProvider provider, int msg) {
+		Array<TelegramProvider> providers = msgProviders.get(msg);
+		if (providers == null) {
+			// Associate an empty unordered array with the message code
+			providers = new Array<TelegramProvider>(false, 16);
+			msgProviders.put(msg, providers);
+		}
+		providers.add(provider);
+	}
+
+	/** Registers a provider for a selection of message types.
+	 * @param provider the provider to add
+	 * @param msgs the message codes */
+	public void addProviders (TelegramProvider provider, int... msgs) {
+		for (int msg : msgs)
+			addProvider(provider, msg);
+	}
+
 	/** Unregister the specified listener for the specified message code.
 	 * @param msg the message code
 	 * @param listener the listener to remove
@@ -175,6 +211,25 @@ public void clearListeners () {
 		msgListeners.clear();
 	}
 
+	/** Unregisters all the providers for the specified message code.
+	 * @param msg the message code */
+	public void clearProviders (int msg) {
+		msgProviders.remove(msg);
+	}
+
+	/** Unregisters all the providers for the given message codes.
+	 *
+	 * @param msgs the message codes */
+	public void clearProviders (int... msgs) {
+		for (int msg : msgs)
+			clearProviders(msg);
+	}
+
+	/** Removes all the registered providers for all the message codes. */
+	public void clearProviders () {
+		msgProviders.clear();
+	}
+
 	/** Removes all the telegrams from the queue and releases them to the internal pool. */
 	public void clearQueue () {
 		for (int i = 0; i < queue.size(); i++) {
@@ -187,6 +242,7 @@ public void clearQueue () {
 	public void clear () {
 		clearQueue();
 		clearListeners();
+		clearProviders();
 	}
 
 	/** Sends an immediate message to all registered listeners, with no extra info.

gdx-ai/src/com/badlogic/gdx/ai/msg/TelegramProvider.java

@@ -0,0 +1,31 @@
+/*******************************************************************************
+ * Copyright 2011 See AUTHORS file.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ******************************************************************************/
+
+package com.badlogic.gdx.ai.msg;
+
+/** Telegram providers respond to {@link MessageDispatcher#addListener} by providing optional {@link Telegram#extraInfo} to be sent
+ * in a Telegram of a given type to the newly registered {@link Telegraph}.
+ * @author avianey */
+public interface TelegramProvider {
+	/** Provides {@link Telegram#extraInfo} to dispatch immediately when a {@link Telegraph} is registered for the given message
+	 * type.
+	 * @param msg the message type to provide
+	 * @param receiver the newly registered Telegraph. Providers can provide different info depending on the targeted Telegraph.
+	 * @return extra info to dispatch in a Telegram or null if nothing to dispatch
+	 * @see com.badlogic.gdx.ai.msg.MessageDispatcher#addListener(Telegraph, int)
+	 * @see com.badlogic.gdx.ai.msg.MessageDispatcher#addListeners(Telegraph, int...) */
+	Object provideMessageInfo (int msg, Telegraph receiver);
+}

tests/src/com/badlogic/gdx/ai/tests/TelegramProviderTest.java

@@ -0,0 +1,55 @@
+/*******************************************************************************
+ * Copyright 2011 See AUTHORS file.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ******************************************************************************/
+
+package com.badlogic.gdx.ai.tests;
+
+import com.badlogic.gdx.Gdx;
+import com.badlogic.gdx.ai.msg.MessageDispatcher;
+import com.badlogic.gdx.ai.tests.msg.City;
+import com.badlogic.gdx.ai.tests.utils.GdxAiTest;
+
+/** A simple test to demonstrate telegram providers.<br/>
+ * Build a ideal city where every new citizen say hello to every existing citizens...
+ * @author avianey */
+public class TelegramProviderTest extends GdxAiTest {
+
+	public static final int MSG_TIME_TO_ACT = 0;
+	public static final int MSG_EXISTING_CITIZEN = 1;
+
+	public static void main (String[] args) {
+		launch(new TelegramProviderTest());
+	}
+
+	City city;
+	float elapsedTime;
+
+	@Override
+	public void create () {
+		elapsedTime = 0;
+		// build a new city
+		city = new City();
+
+	}
+
+	@Override
+	public void render () {
+		elapsedTime += Gdx.graphics.getRawDeltaTime();
+		if (elapsedTime > 0.8f) {
+			MessageDispatcher.getInstance().dispatchMessage(null, MSG_TIME_TO_ACT);
+			elapsedTime = 0;
+		}
+	}
+}

tests/src/com/badlogic/gdx/ai/tests/msg/Citizen.java

@@ -0,0 +1,59 @@
+/*******************************************************************************
+ * Copyright 2011 See AUTHORS file.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ******************************************************************************/
+
+package com.badlogic.gdx.ai.tests.msg;
+
+import com.badlogic.gdx.Gdx;
+import com.badlogic.gdx.ai.msg.MessageDispatcher;
+import com.badlogic.gdx.ai.msg.Telegram;
+import com.badlogic.gdx.ai.msg.TelegramProvider;
+import com.badlogic.gdx.ai.msg.Telegraph;
+import com.badlogic.gdx.ai.tests.TelegramProviderTest;
+
+/** @author avianey */
+public class Citizen implements Telegraph, TelegramProvider {
+
+	static int NUM = 0;
+
+	final int num;
+	final House house;
+
+	public Citizen (House house) {
+		this.num = NUM++;
+		this.house = house;
+		Gdx.app.log(Citizen.class.getSimpleName() + " " + num, "Hi there, I'm new in town and I live in house number " + house.num);
+		MessageDispatcher.getInstance().addListener(this, TelegramProviderTest.MSG_EXISTING_CITIZEN);
+		MessageDispatcher.getInstance().addProvider(this, TelegramProviderTest.MSG_EXISTING_CITIZEN);
+	}
+
+	@Override
+	public boolean handleMessage (Telegram msg) {
+		Citizen citizen = (Citizen)msg.extraInfo;
+		// greet only if not in the same house
+		if (this.house.num != citizen.house.num) {
+			Gdx.app.log(Citizen.class.getSimpleName() + " " + num, "Hi " + Citizen.class.getSimpleName() + " " + citizen.num
+				+ ", I'm your new neighbour");
+		}
+		return false;
+	}
+
+	@Override
+	public Object provideMessageInfo (int msg, Telegraph receiver) {
+		// when a new citizen come to town we tell him that we exists
+		return this;
+	}
+
+}

tests/src/com/badlogic/gdx/ai/tests/msg/City.java

@@ -0,0 +1,47 @@
+/*******************************************************************************
+ * Copyright 2011 See AUTHORS file.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ******************************************************************************/
+
+package com.badlogic.gdx.ai.tests.msg;
+
+import com.badlogic.gdx.Gdx;
+import com.badlogic.gdx.ai.msg.MessageDispatcher;
+import com.badlogic.gdx.ai.msg.Telegram;
+import com.badlogic.gdx.ai.msg.Telegraph;
+import com.badlogic.gdx.ai.tests.TelegramProviderTest;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** @author avianey */
+public class City implements Telegraph {
+
+	List<House> houses;
+
+	public City () {
+		Gdx.app.log(City.class.getSimpleName(), "A new city is born...");
+		houses = new ArrayList<>();
+		MessageDispatcher.getInstance().addListeners(this, TelegramProviderTest.MSG_TIME_TO_ACT);
+	}
+
+	@Override
+	public boolean handleMessage (Telegram msg) {
+		// build a new house
+		if (houses.size() <= 10) {
+			houses.add(new House());
+		}
+		return false;
+	}
+}

tests/src/com/badlogic/gdx/ai/tests/msg/House.java

@@ -0,0 +1,55 @@
+/*******************************************************************************
+ * Copyright 2011 See AUTHORS file.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ ******************************************************************************/
+
+package com.badlogic.gdx.ai.tests.msg;
+
+import com.badlogic.gdx.Gdx;
+import com.badlogic.gdx.ai.msg.MessageDispatcher;
+import com.badlogic.gdx.ai.msg.Telegram;
+import com.badlogic.gdx.ai.msg.Telegraph;
+import com.badlogic.gdx.ai.tests.TelegramProviderTest;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** @author avianey */
+public class House implements Telegraph {
+
+	static int NUM = 0;
+
+	List<Citizen> citizens;
+	final int num;
+
+	public House () {
+		num = NUM++;
+		citizens = new ArrayList<>();
+		Gdx.app.log(House.class.getSimpleName() + " " + num, "New house in town");
+		// Mr & Mrs
+		citizens.add(new Citizen(this));
+		citizens.add(new Citizen(this));
+		MessageDispatcher.getInstance().addListeners(this, TelegramProviderTest.MSG_TIME_TO_ACT);
+	}
+
+	@Override
+	public boolean handleMessage (Telegram msg) {
+		if (citizens.size() < 3) {
+			// new child
+			Gdx.app.log(House.class.getSimpleName() + " " + num, "We're having a baby!");
+			citizens.add(new Citizen(this));
+		}
+		return false;
+	}
+}