eXo Social provides a way to create groups and to share data and applications: the space. A space has it's own activity stream in which applications or members can publish information. In each space, members share applications and an openSocial dashboard.

To manipulate the spaces, you will use the SpaceService. To get an instance of this class, you will need to get current PortalContainer instance.
h1. Spaces Management {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Space_Management}
h2. Create a space {anchor:id=SOCref.Developer_Ref.Developer_document_Spaces.Space_Management.Create_Space}
The following example shows 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);
    // We verify if there is no space already created
    Space space = spaceService.getSpaceByName(spaceName);
    if (space == null) {
      space = new Space();
      space.setName(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);
      //We create the space
      space = spaceService.createSpace(space, creator);
      //We initialize the applications
      spaceService.initApp(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}
We can add a portlet or gadget applications into spaces. Once added, all members of the space can use that application. The following code shows how to add an application into a space :

{code: java}
public void addApplicationToSpace() throws SpaceException {
  //Your portlet name
  String appId = "AnyGadgetOrAnyPortletName";
  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);

  //we 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. With eXo Social, we can find it in social-portlet.war and social.war. 
{note}

h1. Members Management  {anchor:id=SOCref.Developer_Ref.Developer_document_Space.Members_Management}
The SpaceService allows you to manage the spaces' members.Here is how you would add a now member to a space:
{code:java}
String spaceName = "mySpace";

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

Space space = service.getSpaceByName(spaceName);
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 is happening in spaces, you need to extend SpaceListenerPlugin and register it. Every method takes a SpaceLifeCycleEvent object as parameter that contain the information about the event and it's context.

The events available are:

- spaceCreated: this event is called right after space is created successfully with its applications.
- spaceRemoved: this event is called right after a space is removed: application's removed, its group and group navigation is removed
- applicationAdded: this event is called right after an application is added (installed) to a space
- applicationActivated: this event is called right after an application is activated.
- applicationDeactivated: this event is called right after an application is deactivated.
- applicationRemoved: this event is called right after an application is removed from a space.
- joined: this event is called right after a user joins a space.
- left: this event is called right after a space member leaves its space.
- grantedLead: this event is called right after a user is grated space's manager role.
- revokedLead: this event is called right after a 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 the [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, hook it to the SpaceService like this :
{code:xml}
<external-component-plugins>
  <target-component>org.exoplatform.social.space.SpaceService</target-component>
  <component-plugin>
    <name>SpaceActivityPublisher</name>
    <set-method>addSpaceListener</set-method>
    <type>org.mycompany.MySpaceListenerPlugin</type>
  </component-plugin>
</external-component-plugins>
{code}
