After a space has been defined in the metaspace, it can then be joined by applications and will be automatically joined by agents if the space is distributed. A space can be joined, and a valid space object obtained, by invoking the getSpace method of the
Metaspace object, which takes a space name and a distribution role as arguments. The space name must be the name of a space defined in the metaspace, and the role specifies if the application wants to join the space as a seeder or as a 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.
A successful invocation of the metaspace’s getSpace method will return a reference to a
Space object that can then be used to interact with the space. Users should also remember that 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 will 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 that second
getSpace call). An application's role for a space can also be adjusted using the Space's
setDistributionRole method.
An application can leave a space by invoking the space object's close() method (or, in C, by invoking
tibasSpace_Free), or by stopping the listeners or browsers that may have joined the space automatically when created.
As the space object is reference-counted, when created from a metaspace object, the space will actually be left by the process only when the space object's close() method is invoked an equal number of times to the metaspace's
getSpace method for that particular space. Just like the application’s distribution role in the space can be adjusted by subsequent calls to
getSpace with different roles, the application’s distribution role in the space will be adjusted when
close() is invoked on the instances of the Space object returned by each call to
getSpace.
If browsers or listeners where created and not terminated when close() is invoked, the process will not leave the space until those browsers or listeners are terminated. You can forcefully leave the space and terminate any existing browsers and listeners on the space by invoking the
closeAll() method.