The getSpace Method

After a space has been defined in the metaspace, applications can join the space— and as-agents started in the network automatically join the space if the space is distributed.

With the Java API, you join a space by invoking the getSpace method in the Metaspace class.

The getSpace method has the following signature:

public abstract Space getSpace(java.lang.String spaceName,
             Member.DistributionRole distributionRole)
                        throws ASException

The getSpace method has the following parameters:

spaceName

Must be the name of a space defined in the metaspace

DistributionRole

 Specifies the role for the application. Can be SEEDER or LEECH.

In Java, there is a second signature for the getSpace method which does not take a role argument, and can be used to join a space with a distribution role of leech.

In the C API, the equivalent function is tibasMetaspace_GetSpace().

Spaces are also automatically joined (with a role of leech) as needed when creating a listener or a browser on the space from the metaspace.

A successful invocation of the metaspace’s getSpace method returns a reference to a Space object that can then be used to interact with the space.

Note: No space operation—other than getting the space’s name and its definition, or creating a listener or browser on the space—will succeed until the space is in the READY state.

The space object is reference-counted, meaning that successive calls to getSpace do not result in the space being joined more than once. However. the process' role for the space can be adjusted by multiple calls to getSpace: a first call may cause the process to join the Space as a Leech, and a following call may change the role to Seeder (and the role will revert back to Leech when leave is called on the space object reference returned by the second getSpace call). An application's role for a space can also be adjusted using the Space's setDistributionRole method.