eXo Social provides a way to create groups and to share data and applications by spaces. A space has its own activity stream in which applications or members can publish information. In each space, members use applications together with shared data.

To manipulate the spaces, you will use the SpaceService. To get an instance of this class, you need to get the current _PortalContainer_ instance.

h1. Spaces Management  {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Space_Management}

The following example will show how to create a space:

{code:java}
package org.exoplatform.social.sample;

import org.exoplatform.container.PortalContainer;
import org.exoplatform.social.application.impl.DefaultSpaceApplicationHandler;
import org.exoplatform.social.space.Space;
import org.exoplatform.social.space.SpaceException;
import org.exoplatform.social.space.SpaceService;

public class SpaceCreationSample {

  public void createSpace() throws SpaceException {
    String spaceName = "mySpace";
    String creator = "jeremi";
    PortalContainer container = PortalContainer.getInstance();
    SpaceService spaceService = (SpaceService) container.getComponentInstanceOfType(SpaceService.class);
    // verify if there is no space already created
    Space space = spaceService.getSpaceByDisplayName(spaceName);
    if (space == null) {
      space = new Space();
      space.setDisplayName(spaceName);
      space.setRegistration(Space.OPEN);
      space.setDescription("space description"); 
      //DefaultSpaceApplicationHander is the default implementation of SpaceApplicationHandler. You can create your own by extending SpaceApplicationHandler. The default type is "classic" (DefaultSpaceApplicationHandler.NAME = clasic)
      space.setType(DefaultSpaceApplicationHandler.NAME);
      //create the space
      space = spaceService.createSpace(space, creator);
      //initialize the applications
      spaceService.initApps(space);
      
    }
  }
}
{code}

h1. Space's applications management  {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Space_applications_managemnet}

h2. Add an application to a space  {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Add_application_to_a_space}
You can add portlet or gadget applications to spaces. Once added, all members of the space can use that application. The following code shows you how to add an application to a space:

{code:java}
public void addApplicationToSpace() throws SpaceException {
  //Your portlet name
  String appId = "SocialBannerPortlet";
  String spaceId = "zunSpace";

  //get container to get other registered components
  PortalContainer container = PortalContainer.getInstance();

  //get space service for installing operations
  SpaceService spaceService = (SpaceService) container.getComponentInstanceOfType(SpaceService.class);

  //install application for the space
  spaceService.installApplication(spaceId, appId);

  //you must activate installed application to be able to use it
  spaceService.activateApplication(spaceId, appId);
}
{code}

{note}
_appId_ is the portlet or gadget name as defined in _portlet.xml_ or _gadget.xml_ in the web-app. You can find it in _social-portlet.war_ and _social.war_.
{note}


h2. Remove an application from a space {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Remove_application_from_space}

You can remove portlet or gadget applications from a space and the members of this space will not see them anymore. The following code shows you how to remove an application from a space:
{code:java}
public void removeApplicationFromSpace() throws SpaceException {
  //Your portlet name
  String appId = "SocialBannerPortlet";
  String appName = "SocialBannerPortlet1"
  String spaceId = "zunSpace";

  //get container to get other registered components
  PortalContainer container = PortalContainer.getInstance();

  //get space service for installing operations
  SpaceService spaceService = (SpaceService) container.getComponentInstanceOfType(SpaceService.class);

  //install application for the space
  spaceService.removeApplication(spaceId, appId, appName);
}
{code}


h1. Space's members management	 {anchor:id=SOCref.Developer_Ref.Developer_document_Space.Members_Management}
SpaceService allows you to manage the spaces' members. Here is the way to add a new member to a space:
{code:java}
String spacePrettyName = "mySpace";

PortalContainer container = PortalContainer.getInstance();
SpaceService spaceService = (SpaceService) container.getComponentInstanceOfType(SpaceService.class);

Space space = service.getSpaceByPrettyName(spacePrettyName);
if (space != null) {
    spaceService.addMember(space, "mary");
}
{code}


h1. Listener to a space lifecycle  {anchor:id=SOCref.Developer_Ref.Developer_document_Space.Listener_to_a_space_lifecycle}
To receive notifications of what are happening in spaces, you need to extend _SpaceListenerPlugin_ and register it. Every method takes a _SpaceLifeCycleEvent_ object as a parameter that contains the information about the event and its context.

The available events are:

* _spaceCreated_: This event is called right after a space is created successfully with its applications.
* _spaceRemoved_: This event is called right after the space is removed. It means all the applications of the space are removed, its group and group navigation are removed.
* _applicationAdded_: This event is called right after an application is added (installed) to the space.
* _applicationActivated_: This event is called right after an application is activated in the space.
* _applicationDeactivated_: This event is called right after an application is deactivated.
* _applicationRemoved_: This event is called right after an application is removed from the space.
* _joined_: This event is called right after a user joins the space.
* _left_: This event is called right after a space member leaves its space.
* _grantedLead_: This event is called right after a user is granted the space's manager role.
* _revokedLead_: This event is called right after the space's manager is revoked his role to be a space member.

{code:java}
import org.exoplatform.social.space.lifecycle.SpaceListenerPlugin;

public class MySpaceListenerPlugin extends SpaceListenerPlugin {
...
}
{code}

As an example, see [SpaceActivityPublisher|http://fisheye.exoplatform.org/browse/social/trunk/component/exosocial/src/main/java/org/exoplatform/social/space/SpaceActivityPublisher.java?r=HEAD] that publishes an activity based on an event that happened in a space.

To register your listener, configure it as a plugin to the SpaceService like this:

{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.social.core.space.spi.SpaceService</target-component>
  <component-plugin>
    <name>SpaceActivityPublisher</name>
    <set-method>addSpaceListener</set-method>
    <type>org.mycompany.MySpaceListenerPlugin</type>
  </component-plugin>
</external-component-plugins>
{code}
