Merge pull request #10 from SEPIA-Framework/dev

Core tools update to 2.2.0 for SEPIA-Home v2.2.0

Author: fquirin

pom.xml

@@ -4,7 +4,7 @@
 
     <groupId>net.b07z.sepia.server.core</groupId>
     <artifactId>sepia-core-tools</artifactId>
-    <version>2.1.0</version>
+    <version>2.2.0</version>
     <name>SEPIA Core-Tools</name>
     <description>The Core-Tools repository contains classes and methods that are shared by all SEPIA servers and other tools like the SDK.</description>
     <url>https://github.com/SEPIA-Framework/sepia-core-tools-java</url>
@@ -61,6 +61,23 @@
 					<finalName>sepia-core-tools-v${project.version}</finalName>
 				</configuration>
 			</plugin>
+			<!-- force certain surefire version for testing -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<version>3.0.0-M3</version>
+			</plugin>
+			
+			<!-- Java docs, use with: mvn javadoc:jar -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>3.0.1</version>
+				<configuration>
+					<doclint>none</doclint> <!-- TODO: fix errors found by linter -->
+					<finalName>sepia-core-tools-v${project.version}</finalName>
+				</configuration>
+			</plugin>
 		</plugins>
 	</build>
 
@@ -88,7 +105,7 @@
         <dependency>
             <groupId>com.fasterxml.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
-            <version>2.9.7</version>
+            <version>2.9.8</version>
         </dependency>
         <dependency>
             <groupId>commons-lang</groupId>
@@ -121,6 +138,14 @@
 		    <version>4.5.3</version>
 		</dependency>
 
+		<!-- Java 9+ support -->
+		<dependency>
+		    <groupId>javax.xml.bind</groupId>
+		    <artifactId>jaxb-api</artifactId>
+		    <version>2.3.1</version>
+		</dependency>
+		
+		<!-- Testing -->
 		<dependency>
       		<groupId>junit</groupId>
       		<artifactId>junit</artifactId>
@@ -164,4 +189,4 @@
     	<url>https://github.com/SEPIA-Framework/sepia-core-tools-java/tree/master</url>
 	</scm>
 
-</project>
+</project>

src/main/java/net/b07z/sepia/server/core/assistant/ACTIONS.java

@@ -32,7 +32,6 @@ public class ACTIONS {
 	final public static String OPEN_LIST = "open_list";				//tell client to open a user specific list, param.: "listInfo" : {"indexType":...}
 	final public static String EXTEND_REQUEST = "extend_request";		//tell client that this request will take longer and he should prepare for that
 	final public static String SHOW_ABORT_OPTION = "show_abort";		//tell client to show an abort option
-	//deprecated: final public static String SKIP_TTS = "skip_tts";			//tell client to prevent TTS sound output (best used together with PLAY_AUDIO)
 	final public static String PLAY_AUDIO_URL = "play_audio_url";			//tell client to play a single audio file from url, parameters: audio_url
 	final public static String PLAY_AUDIO_STREAM = "play_audio_stream";	//tell client to play a continuous audio stream, parameters: audio_url, audio_title, audio_img, audio_type
 	final public static String STOP_AUDIO_STREAM = "stop_audio_stream";	//tell client to stop the running audio stream
@@ -42,11 +41,11 @@ public class ACTIONS {
 	final public static String ALARM = "alarm";					//tell client to set an alarm, parameters: tbd
 	final public static String REMINDER = "reminder";			//tell client to set an reminder, parameters: tbd
 	final public static String APPOINTMENT = "appointment";		//tell client to set an appointment in the calendar, parameters: tbd
+	final public static String SWITCH_LANGUAGE = "switch_language";		//tell client to switch language, parameters: language_code
 
 	//possible next actions:
 	//public static String STREAMING_REQUEST = "streaming_request";		//tell the client that he has to expect an answer that gets streamed
 	//public static String GET_HTML_META_INFO = "get_html_meta_info";	//tell client to open an url, get meta info when the page is loaded and say it, parameters: meta_tags, add_answer
-	//public static String EXECUTE_CMD = "execute_cmd";					//tell client to execute an command, parameters: command
 
 	//ACTION OPTIONS
 	final public static String SKIP_TTS = "skipTTS";

src/main/java/net/b07z/sepia/server/core/assistant/CMD.java

@@ -34,6 +34,7 @@ public class CMD {
 	final public static String LISTS = "lists";						//parameters:	type, action, info
 	final public static String LOCATION = "location";					//parameters:	search, poi (like italian restaurant, supermarket etc. ...)
 	final public static String MATCH = "match";						//parameters: 	info
+	final public static String MESH_NODE_PLUGIN = "mesh_node_plugin";		//parameters: 	node_url, node_plugin_name, node_plugin_data, reply_success, reply_fail 
 	final public static String MOBILITY = "mobility";					//parameters:	location_start, location_end, type, time
 	final public static String MOVIES = "movies";						//parameters:	search, type (genre), info (actor,director)
 	final public static String MUSIC = "music";						//parameters:	search, type (genre), info (artist?)

src/main/java/net/b07z/sepia/server/core/assistant/PARAMETERS.java

@@ -104,10 +104,17 @@ public class PARAMETERS {
 	final public static String LIST_TYPE = "list_type";			//type of list (e.g. shopping, todo, ...)
 	final public static String LIST_SUBTYPE = "list_subtype";	//sub-type aka name of list (e.g. my great ..., my macys ...)
 
+	//MESH NODE PLUGIN
+	final public static String MESH_NODE_URL = "node_url";					//URL to mesh node
+	final public static String MESH_NODE_PLUGIN_NAME = "node_plugin_name";	//name of mesh node plugin
+	final public static String MESH_NODE_PLUGIN_DATA = "node_plugin_data";	//data (e.g. as JSON string) for node plugin
+	
 	//------------ control parameters -------------
 
 	//CHATS and QUESTIONS
-	final public static String REPLY = "reply";					//a reply the assistant should give submitted as parameter from client
+	final public static String REPLY = "reply";					//a reply the assistant should give submitted as parameter from client (for certain services that use it)
+	final public static String REPLY_SUCCESS = "reply_success";				//a reply used for success (for certain services that use it)
+	final public static String REPLY_FAIL = "reply_fail";					//a reply used for fail (for certain services that use it)
 	final public static String ANY_ANSWER = "any_answer";		//if you don't have a particular parameter that is missing but you ask a previously undefined question you can store the answer here. Maybe add dialog_state to it.
 
 	//CUSTOM SERVICES (do we still need this?)

src/main/java/net/b07z/sepia/server/core/data/Answer.java

@@ -14,6 +14,15 @@
 
 import org.json.simple.JSONObject;
 
+/**
+ * This class contains all required info for answers given by the assistant.
+ * Answers can have a number of parameters like character (neutral, cool, ...), when to trigger (first time, first repetition, etc.)
+ * and many more. If you create a custom answer pool (e.g. inside a service) use this constructor to get a good set of parameters:<br>
+ * Answer(Language language, String type, String text, Character character, int repetition, int mood)
+ * 
+ * @author Florian Quirin
+ *
+ */
 public class Answer {
 
 	//database types to organize commands
@@ -42,26 +51,61 @@ public class Answer {
 	private Map<String, Object> data;		//any additional data we did not think of right now
 	private String date;
 
+	/**
+	 * Every answer can be assigned to a certain assistant 'character' like 'cool' or 'rude' (or 'neutral').
+	 */
 	public enum Character {
 		neutral, rude, cool, polite
 	}
 
+	/**
+	 * Usually you want to use another constructor: {@link Answer}(Language language, String type, String text, Character character, int repetition, int mood)
+	 */
 	public Answer() {
 		// needed for Jackson
 	}
 
+	/**
+	 * Create an answer with default settings.
+	 * @param language - language code for this answer
+	 * @param type - answer key, basically an ID to find an answer in the pool
+	 * @param text - actual answer (variables like &lt1&gt, &lt2&gt ... are supported)
+	 */
 	public Answer(Language language, String type, String text) {
 		this(language, type, text, Character.neutral);
 	}
-
+	/**
+	 * Create an answer with default settings and custom character.
+	 * @param language - language code for this answer
+	 * @param type - answer key, basically an ID to find an answer in the pool
+	 * @param text - actual answer (variables like &lt1&gt, &lt2&gt ... are supported)
+	 * @param character - answer {@link Character} like "neutral", "rude", "cool"
+	 */
 	public Answer(Language language, String type, String text, Character character) {
 		this(language, type, text, character, 0, 5);
 	}
 
+	/**
+	 * Build a new answer with all relevant information.
+	 * @param language - language code for this answer
+	 * @param type - answer key, basically an ID to find an answer in the pool
+	 * @param text - actual answer (variables like &lt1&gt, &lt2&gt ... are supported)
+	 * @param character - answer {@link Character} like "neutral", "rude", "cool"
+	 * @param repetition - when will this answer be triggered? First try (0), first repeat (1), following repeats (2)
+	 * @param mood - mood level that this answer will be used from 0-10. Sad (0), neutral (5), happy (10)
+	 */
 	public Answer(Language language, String type, String text, Character character, int repetition, int mood) {
 		this(language, type, text, Collections.singletonList(character), repetition, mood);
 	}
-	
+	/**
+	 * Build a new answer with all relevant information.
+	 * @param language - language code for this answer
+	 * @param type - answer key, basically an ID to find an answer in the pool
+	 * @param text - actual answer (variables like &lt1&gt, &lt2&gt ... are supported)
+	 * @param characters - multiple answer {@link Character} like "neutral", "rude", "cool"
+	 * @param repetition - when will this answer be triggered? First try (0), first repeat (1), following repeats (2)
+	 * @param mood - mood level that this answer will be used from 0-10. Sad (0), neutral (5), happy (10)
+	 */
 	public Answer(Language language, String type, String text, List<Character> characters, int repetition, int mood) {
 		this(language, type, text, characters, repetition, mood,
 				ConfigDefaults.defaultAssistantUserId, Defaults.IMPORT_SOURCE, true, false, false, null,
@@ -70,6 +114,7 @@ public Answer(Language language, String type, String text, List<Character> chara
 	}
 
 	/**
+	 * Usually you want to use another constructor: {@link Answer}(Language language, String type, String text, Character character, int repetition, int mood)
 	 * @param isPublic is this visible for everybody, if not, it's a private answer
 	 * @param isLocal is this run on the local home server?
 	 */
@@ -101,14 +146,23 @@ public Answer(Language language, String type, String text, List<Character> chara
 		this.date = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss").format(new Date());
 	}
 
+	/**
+	 * Language in use for this answer.
+	 */
 	public Language getLanguage() {
 		return language;
 	}
 
+	/**
+	 * This is the answer key, basically an ID to find an answer or list of answers in the pool (DB, file or memory).
+	 */
 	public String getType() {
 		return type;
 	}
 
+	/**
+	 * The actual answer in the given language.
+	 */
 	public String getText() {
 		return text;
 	}

src/main/java/net/b07z/sepia/server/core/data/CmdMap.java

@@ -25,11 +25,21 @@ public class CmdMap {
 	private List<String> permissions;
 
 	@SuppressWarnings("unchecked")
+	/**
+	 * Import command map from JSON.
+	 * @param entry
+	 */
 	public CmdMap(JSONObject entry){
 		this.command = JSON.getString(entry, "command");
 		this.services = new ArrayList<>((JSONArray)entry.get("services"));
 		this.permissions = new ArrayList<>((JSONArray)entry.get("permissions"));
 	}
+	/**
+	 * Create a new command map.
+	 * @param command
+	 * @param services
+	 * @param permissions
+	 */
 	public CmdMap(String command, List<String> services, List<String> permissions){
 		this.command = command;
 		this.services = services;
@@ -52,6 +62,10 @@ public boolean equals(Object map){
 			return false;
 		}
 	}
+	@Override
+	public String toString(){
+		return (this.command + " - services: " + this.services.size());
+	}
 
 	public String getCommand(){
 		return command;

src/main/java/net/b07z/sepia/server/core/java/MaxSizeMap.java

@@ -0,0 +1,47 @@
+package net.b07z.sepia.server.core.java;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * A Map implementation that uses {@LinkedHashMap} to features to keep the size limited to a maximum and drop the oldest entry on overflow.<br>
+ * NOTE: Check the constructor on notes about concurrency.  
+ * 
+ * @author Florian Quirin
+ *
+ * @param <K>
+ * @param <V>
+ */
+public class MaxSizeMap<K, V> extends LinkedHashMap<K, V> {
+
+	private static final long serialVersionUID = 1L;
+	
+	private int maxKeysSize;
+	
+	/**
+	 * Create a {@LinkedHashMap} that automatically removes the oldest entry when size is exceeded.<br>
+	 * <br>
+	 * IMPORTANT: This map (as is it basically a linked hash map) can run into concurrency problems, use {@link #getSynchronizedMap(int)}
+	 * or build your own Collections.synchronizedMap(...) if you access the list from multiple threads.
+	 * @param maxSize
+	 */
+	public MaxSizeMap(int maxSize){
+		super(maxSize + 1);
+		this.maxKeysSize = maxSize;
+	}
+	/**
+	 * Create a synchronized version of this map.
+	 * @param maxSize
+	 * @return
+	 */
+	public static <T> Map<String, T> getSynchronizedMap(int maxSize){
+		return Collections.synchronizedMap(new MaxSizeMap<String, T>(maxSize));
+	}
+	
+	@Override
+    protected boolean removeEldestEntry(final Map.Entry<K, V> eldest) {
+        return size() > maxKeysSize;
+    }
+
+}

src/main/java/net/b07z/sepia/server/core/server/RequestGetOrFormParameters.java

@@ -33,13 +33,21 @@ public String[] getStringArray(String key) {
 	@Override
 	public JSONObject getJson(String key) {
 		String jsonString = request.queryParams(key);
-		return JSON.parseStringOrFail(jsonString);
+		if (jsonString != null){
+			return JSON.parseStringOrFail(jsonString);
+		}else{
+			return null;
+		}
 	}
 
 	@Override
 	public JSONArray getJsonArray(String key) {
 		String jsonString = request.queryParams(key);
-		return JSON.parseStringToArrayOrFail(jsonString);
+		if (jsonString != null){
+			return JSON.parseStringToArrayOrFail(jsonString);
+		}else{
+			return null;
+		}
 	}
 
 	@Override

src/main/java/net/b07z/sepia/server/core/server/SparkJavaFw.java

@@ -143,6 +143,8 @@ public static String returnNoAccess(Request request, Response response){
 
 	/**
 	 * Return simple access-restricted message with custom error code.
+	 * @param errorCode - code returned from authenticator - 1: communication error, 2: access denied, ...
+	 * @return
 	 */
 	public static String returnNoAccess(Request request, Response response, int errorCode){
 		if (errorCode == 2){

src/main/java/net/b07z/sepia/server/core/server/Validate.java

@@ -1,6 +1,7 @@
 package net.b07z.sepia.server.core.server;
 
 import net.b07z.sepia.server.core.tools.Debugger;
+import net.b07z.sepia.server.core.tools.Is;
 import net.b07z.sepia.server.core.tools.Security;
 import spark.Request;
 
@@ -42,12 +43,13 @@ public static String getLocalSignature(Request request, String challenge, long t
 	 */
 	public static boolean validateInternalCall(Request request, String submittedKey, String sharedServerKey) {
 		//TODO: make this more secure by adding a white-list of IPs or something ...
-		if (submittedKey != null && submittedKey.equals(sharedServerKey)){
-			return true;
-		}else if (submittedKey != null){
-			Debugger.println("Invalid internal API call from " + request.ip(), 1);
+		if (Is.nullOrEmpty(submittedKey) || Is.nullOrEmpty(sharedServerKey)){
 			return false;
+		}
+		if (submittedKey.equals(sharedServerKey)){
+			return true;
 		}else{
+			Debugger.println("Invalid internal API call from " + request.ip(), 1);
 			return false;
 		}
 	}