Merge branch 'develop'

src/ve/ucv/ciens/icaro/libnxtarcontrol/NxtARControlProtocol.java

@@ -28,7 +28,7 @@ import ve.ucv.ciens.icaro.libnxtarcontrol.DecodedControlAction.Motor;
  * @see <a href="http://www.lejos.org">The LejOS operating system.</a>
  * @see <a href="https://github.com/sagge-miky/NxtAR-core">NxtAR-core Github repository.</a>
  * @author Miguel Angel Astor Romero
- * @version 1.0.1
+ * @version 1.1.0
  * @since December 15, 2014
  */
 public class NxtARControlProtocol {
@@ -140,6 +140,111 @@ public class NxtARControlProtocol {
 			}
 
 			if(controlAction != null){
+				success = executeControlAction(controlAction);
+			}
+		}
+
+		return success;
+	}
+
+	/**
+	 * <p>Decodes a protocol message encoded as a byte array of two elements as specified
+	 * in the package definition.</p>
+	 * 
+	 * <p>User actions have precedence over motor recentering and
+	 * this in turn has precedence over other movement actions.
+	 * User actions have precedence in decreasing order; that is, user action 1 has
+	 * precedence over user actions 2 and 3, etc.</p>
+	 * 
+	 * <p>If the message indicates a movement (forward or backward) with all motors off,
+	 * then it is interpreted as a request to stop all motors. A recenter or user action
+	 * with all motors off will be decoded as is and must be interpreted by the user.</p>
+	 * 
+	 * @param message A byte array of size two encoding a message recognized by the protocol. If the array
+	 * has 3 or more elements then only the first 2 are used during the decoding process. 
+	 * @return A {@link DecodedControlAction} instance containing the decoded message.
+	 * @throws IllegalArgumentException If the array is null or has less than 2 elements.
+	 */
+	public DecodedControlAction decodeMessage(final byte[] message) throws IllegalArgumentException{
+		Action action = Action.STOP;
+		Motor motor = Motor.MOTOR_ABC;
+		DecodedControlAction controlAction;
+
+		if(message == null)
+			throw new IllegalArgumentException("Message is null.");
+
+		if(message.length < 2)
+			throw new IllegalArgumentException("Message is too short. Length of message is " + message.length);
+
+		// Decode the message.
+		boolean motorA    = (message[0] & MOTOR_A)   > 0 ? true : false;
+		boolean motorB    = (message[0] & MOTOR_B)   > 0 ? true : false;
+		boolean motorC    = (message[0] & MOTOR_C)   > 0 ? true : false;
+		boolean recenter  = (message[0] & RECENTER)  > 0 ? true : false;
+		boolean user1     = (message[0] & USER_1)    > 0 ? true : false;
+		boolean user2     = (message[0] & USER_2)    > 0 ? true : false;
+		boolean user3     = (message[0] & USER_3)    > 0 ? true : false;
+		int     direction = (message[0] & DIRECTION) > 0 ? BasicMotorPort.FORWARD : BasicMotorPort.BACKWARD;
+
+		// Set the action flag. 
+		if(user1 || user2 || user3){
+			if     (user1) action = Action.USER_1;
+			else if(user2) action = Action.USER_2;
+			else if(user3) action = Action.USER_3;
+		}else if(recenter){
+			action = Action.RECENTER;
+		}else{
+			if(direction == BasicMotorPort.FORWARD){
+				action = Action.MOVE_FORWARD;
+			}else if(direction == BasicMotorPort.BACKWARD){
+				action = Action.MOVE_BACKWARDS;
+			}
+		}
+
+		// Set the motor flag.
+		if(motorA && motorB && motorC){
+			motor = Motor.MOTOR_ABC;
+		}else if(motorA && motorB && !motorC){
+			motor = Motor.MOTOR_AB;
+		}else if(motorA && !motorB && motorC){
+			motor = Motor.MOTOR_AC;
+		}else if(!motorA && motorB && motorC){
+			motor = Motor.MOTOR_BC;
+		}else if(motorA && !motorB && !motorC){
+			motor = Motor.MOTOR_A;
+		}else if(!motorA && motorB && !motorC){
+			motor = Motor.MOTOR_B;
+		}else if(!motorA && !motorB && motorC){
+			motor = Motor.MOTOR_C;
+		}
+
+		// Check for stop condition.
+		if(action == Action.MOVE_FORWARD || action == Action.MOVE_BACKWARDS){
+			if(!motorA && !motorB && !motorC){
+				action = Action.STOP;
+				motor = Motor.MOTOR_ABC;
+			}
+		}
+
+		controlAction = new DecodedControlAction(action, motor, message[1]);
+
+		return controlAction;
+	}
+
+	/**
+	 * <p>Executes an already decoded {@link DecodedControlAction}, calling the user operation
+	 * listeners if needed.</p>
+	 * 
+	 * @param controlAction The action to execute.
+	 * @return True if the action could be executed successfully. False otherwise.
+	 * @throws IllegalArgumentException If controlAction is null.
+	 */
+	public boolean executeControlAction(final DecodedControlAction controlAction) throws IllegalArgumentException{
+		boolean success = false;
+
+		if(controlAction == null){
+			throw new IllegalArgumentException("Control action is null.");
+		}else{
 			switch(controlAction.action){
 			case MOVE_BACKWARDS:
 				switch(controlAction.motor){
@@ -277,95 +382,10 @@ public class NxtARControlProtocol {
 				break;
 			}
 		}
-		}
 
 		return success;
 	}
 
-	/**
-	 * <p>Decodes a protocol message encoded as a byte array of two elements as specified
-	 * in the package definition.</p>
-	 * 
-	 * <p>User actions have precedence over motor recentering and
-	 * this in turn has precedence over other movement actions.
-	 * User actions have precedence in decreasing order; that is, user action 1 has
-	 * precedence over user actions 2 and 3, etc.</p>
-	 * 
-	 * <p>If the message indicates a movement (forward or backward) with all motors off,
-	 * then it is interpreted as a request to stop all motors. A recenter or user action
-	 * with all motors off will be decoded as is and must be interpreted by the user.</p>
-	 * 
-	 * @param message A byte array of size two encoding a message recognized by the protocol. If the array
-	 * has 3 or more elements then only the first 2 are used during the decoding process. 
-	 * @return A {@link DecodedControlAction} instance containing the decoded message.
-	 * @throws IllegalArgumentException If the array is null or has less than 2 elements.
-	 */
-	public DecodedControlAction decodeMessage(byte[] message) throws IllegalArgumentException{
-		Action action = Action.STOP;
-		Motor motor = Motor.MOTOR_ABC;
-		DecodedControlAction controlAction;
-
-		if(message == null)
-			throw new IllegalArgumentException("Message is null.");
-
-		if(message.length < 2)
-			throw new IllegalArgumentException("Message is too short. Length of message is " + message.length);
-
-		// Decode the message.
-		boolean motorA    = (message[0] & MOTOR_A)   > 0 ? true : false;
-		boolean motorB    = (message[0] & MOTOR_B)   > 0 ? true : false;
-		boolean motorC    = (message[0] & MOTOR_C)   > 0 ? true : false;
-		boolean recenter  = (message[0] & RECENTER)  > 0 ? true : false;
-		boolean user1     = (message[0] & USER_1)    > 0 ? true : false;
-		boolean user2     = (message[0] & USER_2)    > 0 ? true : false;
-		boolean user3     = (message[0] & USER_3)    > 0 ? true : false;
-		int     direction = (message[0] & DIRECTION) > 0 ? BasicMotorPort.FORWARD : BasicMotorPort.BACKWARD;
-
-		// Set the action flag. 
-		if(user1 || user2 || user3){
-			if     (user1) action = Action.USER_1;
-			else if(user2) action = Action.USER_2;
-			else if(user3) action = Action.USER_3;
-		}else if(recenter){
-			action = Action.RECENTER;
-		}else{
-			if(direction == BasicMotorPort.FORWARD){
-				action = Action.MOVE_FORWARD;
-			}else if(direction == BasicMotorPort.BACKWARD){
-				action = Action.MOVE_BACKWARDS;
-			}
-		}
-
-		// Set the motor flag.
-		if(motorA && motorB && motorC){
-			motor = Motor.MOTOR_ABC;
-		}else if(motorA && motorB && !motorC){
-			motor = Motor.MOTOR_AB;
-		}else if(motorA && !motorB && motorC){
-			motor = Motor.MOTOR_AC;
-		}else if(!motorA && motorB && motorC){
-			motor = Motor.MOTOR_BC;
-		}else if(motorA && !motorB && !motorC){
-			motor = Motor.MOTOR_A;
-		}else if(!motorA && motorB && !motorC){
-			motor = Motor.MOTOR_B;
-		}else if(!motorA && !motorB && motorC){
-			motor = Motor.MOTOR_C;
-		}
-
-		// Check for stop condition.
-		if(action == Action.MOVE_FORWARD || action == Action.MOVE_BACKWARDS){
-			if(!motorA && !motorB && !motorC){
-				action = Action.STOP;
-				motor = Motor.MOTOR_ABC;
-			}
-		}
-
-		controlAction = new DecodedControlAction(action, motor, message[1]);
-
-		return controlAction;
-	}
-
 	/**
 	 * <p>Adds an {@link UserActionListener} to this object's listeners list calling it's 
 	 * {@link UserActionListener#onListenerRegistered()} method. Adding a listener that
@@ -374,7 +394,7 @@ public class NxtARControlProtocol {
 	 * @param listener The listener to add.
 	 * @throws IllegalArgumentException If listener is null.
 	 */
-	public synchronized void registerUserActionListener(UserActionListener listener) throws IllegalArgumentException{
+	public synchronized void registerUserActionListener(final UserActionListener listener) throws IllegalArgumentException{
 		if(listener == null)
 			throw new IllegalArgumentException("Listener is null.");
 
@@ -392,7 +412,7 @@ public class NxtARControlProtocol {
 	 * @param listener The listener to remove.
 	 * @throws IllegalArgumentException If listener is null.
 	 */
-	public synchronized void removeUserActionListener(UserActionListener listener) throws IllegalArgumentException{
+	public synchronized void removeUserActionListener(final UserActionListener listener) throws IllegalArgumentException{
 		if(listener == null)
 			throw new IllegalArgumentException("Listener is null.");
 
@@ -409,7 +429,7 @@ public class NxtARControlProtocol {
 	 * 
 	 * @param userAction The action that triggered the notification.
 	 */
-	private void notifyListeners(Action userAction, Motor motorFlag, int speed){
+	private void notifyListeners(final Action userAction, final Motor motorFlag, final int speed){
 		switch(userAction){
 		case USER_1:
 			for(UserActionListener listener : userActionListeners)

src/ve/ucv/ciens/icaro/libnxtarcontrol/UserActionListener.java

@@ -24,7 +24,7 @@ import ve.ucv.ciens.icaro.libnxtarcontrol.DecodedControlAction.Motor;
  */
 public interface UserActionListener {
 	/**
-	 * <p>Executes a set of instructions just after the listener has been registered with an {@link NxtARControlProtocol instance}.</p>
+	 * <p>Executes a set of instructions just after the listener has been registered with an {@link NxtARControlProtocol} instance.</p>
 	 */
 	public void onListenerRegistered();
 
@@ -44,7 +44,7 @@ public interface UserActionListener {
 	public void onUserAction3(Motor motorFlag, int speed);
 
 	/**
-	 * <p>Executes a set of instructions just after the listener has been removed from an {@link NxtARControlProtocol instance}.</p>
+	 * <p>Executes a set of instructions just after the listener has been removed from an {@link NxtARControlProtocol} instance.</p>
 	 */
 	public void onListenerRemoved();
 }