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 into 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

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}
The 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 the 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 grated 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 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, 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}
