[core] Functions for joining and leaving a context replies the action…

… status with a boolean value.

Signed-off-by: Stéphane Galland <galland@arakhne.org>

main/apiplugins/io.sarl.core/src/io/sarl/core/bic.sarl

@@ -74,29 +74,43 @@ capacity ExternalContextAccess {
 	 * The parameter <var>expectedDefaultSpaceID</var> is only used to check if
 	 * the caller of this function knows the ID of the default space in the context to
 	 * be involved in. Note that the context must already exists, and the default space
-	 * inside this context must have the sams ID as <var>expectedDefaultSpaceID</var>.
+	 * inside this context must have the same ID as <var>expectedDefaultSpaceID</var>.
 	 * If the given <var>expectedDefaultSpaceID</var> does not match the ID of the
 	 * default space in the context <var>contextID</var>, then the access to the context
 	 * is forbidden.
 	 *
 	 * <p>This actions registers the agent in the default Space of the context with the
 	 * ID <var>contextID</var>.
 	 *
+	 * <p>This function replies {@code false} is the given identifiers corresponds to a context in which
+	 * the agent is already member.
+	 *
 	 * @param contextID the identifier of the context to join.
 	 * @param expectedDefaultSpaceID the known identifier of the default space in the agent context with the given identifier.
+	 * @return {@code true} if the context was joined. {@code false} if the given context id does not corresponds to a known context,
+	 *     or the given space identifier is not the one of the context's default space, or the agent is already member
+	 *     of the context with the given identifier (default context, or any other external context).
 	 * @fires ContextJoined in its inner Context default space (Behaviors#wake).
 	 * @fires MemberJoined in its parent Context default Space 
 	 */
-	def join(contextID : UUID, expectedDefaultSpaceID : UUID) fires ContextJoined, MemberJoined
+	def join(contextID : UUID, expectedDefaultSpaceID : UUID) : boolean fires ContextJoined, MemberJoined
 
 	/**
-	 * Leaves the parent's context. 
+	 * Leaves the parent's context.
+	 *
+	 * <p>Because an agent must be always into a context, this function fails (and replies {@code false}) when
+	 * the context to be leaved is the current default context of the agent, and there is no other context or
+	 * more than 1 other context that could be elected as the new default context.
 	 *
 	 * @param contextID the identifier of the context to leave.
+	 * @return {@code true} if the agent has leaved the context. {@code false} if the agent has not leaved
+	 *     the context: identifier is not related to a joined context, or the identifier if related to
+	 *     the default context, and their is not a unique joined external context that is different than
+	 *     the default context.
 	 * @fires ContextLeft in its inner Context default space (Behaviors#wake).
 	 * @fires MemberLeft in its parent Context default Space 
 	 */
-	def leave(contextID : UUID) fires ContextLeft, MemberLeft
+	def leave(contextID : UUID) : boolean fires ContextLeft, MemberLeft
 
 	/** Replies if the given event was emitted in the given space.
 	 *

sre/io.janusproject/io.janusproject.plugin/src/io/janusproject/kernel/bic/ExternalContextAccessSkill.java

@@ -146,20 +146,19 @@ public AgentContext getContext(UUID contextID) {
 	}
 
 	@Override
-	public void join(UUID futureContext, UUID futureContextDefaultSpaceID) {
+	public boolean join(UUID futureContext, UUID futureContextDefaultSpaceID) {
 		assert futureContext != null;
 		assert futureContextDefaultSpaceID != null;
 
 		if (this.contexts.contains(futureContext)) {
-			return;
+			return false;
 		}
 
 		final AgentContext ac = this.contextRepository.getContext(futureContext);
 		assert ac != null : "Unknown Context"; //$NON-NLS-1$
 
 		if (!futureContextDefaultSpaceID.equals(ac.getDefaultSpace().getSpaceID().getID())) {
-			throw new IllegalArgumentException(MessageFormat.format(Messages.ExternalContextAccessSkill_1,
-					futureContextDefaultSpaceID));
+			return false;
 		}
 
 		this.contexts.add(futureContext);
@@ -168,6 +167,7 @@ public void join(UUID futureContext, UUID futureContextDefaultSpaceID) {
 
 		fireContextJoined(futureContext, futureContextDefaultSpaceID);
 		fireMemberJoined(ac);
+		return true;
 	}
 
 	/**
@@ -194,15 +194,15 @@ protected final void fireMemberJoined(AgentContext newJoinedContext) {
 	}
 
 	@Override
-	public void leave(UUID contextID) {
+	public boolean leave(UUID contextID) {
 		assert contextID != null;
 
 		final AgentContext ac = this.contextRepository.getContext(contextID);
 
 		assert ac != null : "Unknown Context"; //$NON-NLS-1$
 
 		if (!this.contexts.contains(contextID)) {
-			return;
+			return false;
 		}
 
 		// To send this event the agent must still be inside the context and its default space
@@ -211,7 +211,7 @@ public void leave(UUID contextID) {
 
 		((OpenEventSpace) ac.getDefaultSpace()).unregister(getInternalEventBusCapacitySkill().asEventListener());
 
-		this.contexts.remove(contextID);
+		return this.contexts.remove(contextID);
 	}
 
 	/**

sre/io.janusproject/io.janusproject.plugin/src/io/janusproject/kernel/bic/Messages.java

@@ -34,7 +34,6 @@
 public class Messages extends NLS {
 	private static final String BUNDLE_NAME = Messages.class.getPackage().getName() + ".messages"; //$NON-NLS-1$
 	public static String ExternalContextAccessSkill_0;
-	public static String ExternalContextAccessSkill_1;
 	public static String InternalEventBusSkill_0;
 	public static String InternalEventBusSkill_1;
 	public static String InternalEventBusSkill_2;

sre/io.janusproject/io.janusproject.plugin/src/io/janusproject/kernel/bic/messages.properties

@@ -1,5 +1,4 @@
 ExternalContextAccessSkill_0=The context ID ''{0}'' is known by the agent
-ExternalContextAccessSkill_1=The specified default space ID does not match the context ID ''{0}''
 InternalEventBusSkill_0=selfEvent: {0}
 InternalEventBusSkill_1=Dropping an event since the agent is dying: {0}
 InternalEventBusSkill_2=Cannot kill the agent {0}: {1}