diff --git a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec index f57ac493cb..07af4e5c7d 100644 --- a/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec +++ b/docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/tutorials/PingPongSpace.spec @@ -167,14 +167,11 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ * * The sub-space is located in the default context. * For creating or joining it, we must use the - * `getOrCreateSpace` function. This function - * takes the type of the space specification that - * permits to create an instance of the desired space. - * The second argument is the identifier of the - * new space. - * The `getOrCreateSpace` function creates a new - * space if there is no existing space with the given - * identifier, or it replies the existing space. + * `getOrCreateSpaceWithSpec` function. + * This function searches for a space, which was + * created with the given specification. If there + * is no space, the space identifier is used + * for creating a new space. * * After retrieving the instance of the space, * it is mandatory to register the agent for @@ -195,7 +192,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -234,7 +231,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -312,7 +309,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -383,7 +380,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -444,7 +441,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -478,7 +475,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -527,7 +524,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -587,7 +584,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) @@ -673,7 +670,7 @@ describe "Agent Communication in Sub-Space with the Ping Pong Agents"{ var space : OpenEventSpace on Initialize { - space = defaultContext.getOrCreateSpace( + space = defaultContext.getOrCreateSpaceWithSpec( typeof(OpenEventSpaceSpecification), occurrence.parameters.get(0) as UUID) space.register(asEventListener()) diff --git a/plugins/io.sarl.lang.core/src/io/sarl/lang/core/AgentContext.java b/plugins/io.sarl.lang.core/src/io/sarl/lang/core/AgentContext.java index c2b263b0a0..783723276a 100644 --- a/plugins/io.sarl.lang.core/src/io/sarl/lang/core/AgentContext.java +++ b/plugins/io.sarl.lang.core/src/io/sarl/lang/core/AgentContext.java @@ -80,22 +80,71 @@ S createSpace(Class> spec, */ SynchronizedCollection getSpaces(Class> spec); - /** Retreive or create an instance of space following the given specification. - * This function tries to find a space that fits the given specification. - * If none was found, this function create a new space in the same way as - * {@link #createSpace(Class, UUID, Object...)}. + /** Retreive or create an instance of space which was created with the given specification. + *

+ * This function tries to find a space that was created with the given specification. + * If none was found, this function creates a new space with the given space + * identifier and creation parameters. + *

+ * Caution: The spaceUUID parameter is used only + * if no existing space created with the given specification was found. * * @param - type of the replied space. - * @param spec - specification of the space to create. - * @param spaceUUID - identifier of the new space. + * @param spec - specification of the space to retreive/create. + * @param spaceUUID - identifier used only when creating the space. * @param creationParams - parameters to pass to the space constructor. - * @return the new space, never null. + * @return the space, never null. + * @see #getOrCreateSpaceWithID(UUID, Class, Object...) * @see #createSpace(Class, UUID, Object...) * @see #getSpace(UUID) + * @deprecated see {@link #getOrCreateSpaceWithSpec(Class, UUID, Object...)} */ + @Deprecated S getOrCreateSpace(Class> spec, UUID spaceUUID, Object... creationParams); + /** Retreive or create an instance of space which was created with the given specification. + *

+ * This function tries to find a space that was created with the given specification. + * If none was found, this function creates a new space with the given space + * identifier and creation parameters. + *

+ * Caution: The spaceUUID parameter is used only + * if no existing space created with the given specification was found. + * + * @param - type of the replied space. + * @param spec - specification of the space to retreive/create. + * @param spaceUUID - identifier used only when creating the space. + * @param creationParams - parameters to pass to the space constructor. + * @return the space, never null. + * @see #getOrCreateSpaceWithID(UUID, Class, Object...) + * @see #createSpace(Class, UUID, Object...) + * @see #getSpace(UUID) + */ + S getOrCreateSpaceWithSpec(Class> spec, + UUID spaceUUID, Object... creationParams); + + /** Retreive or create an instance of space with the given identifier. + *

+ * This function tries to find a space with the given identifier. + * If none was found, this function creates a new space with the given + * specification and creation parameters. + *

+ * Caution: The spaceUUID parameter is given to + * the specification when creating the space. + * + * @param - type of the replied space. + * @param spaceUUID - identifier of the space. + * @param spec - specification of the space for creating the space. + * @param creationParams - parameters to pass to the space constructor. + * @return the space, never null. + * @see #getOrCreateSpaceWithID(UUID, Class, Object...) + * @see #createSpace(Class, UUID, Object...) + * @see #getSpace(UUID) + */ + S getOrCreateSpaceWithID(UUID spaceUUID, + Class> spec, Object... creationParams); + /** Retreive, but do not create, an instance of space following the given ID. * This function tries to find a space that fits the given specification. * If none was found, this function replies null.