de.fu_berlin.inf.dpp.session.ISarosSession Interface Reference

Inheritance diagram for de.fu_berlin.inf.dpp.session.ISarosSession:

List of all members.

Public Member Functions
List< User >	getUsers ()
List< User >	getRemoteUsers ()
void	initiatePermissionChange (User user, Permission newPermission) throws CancellationException, InterruptedException
void	setPermission (User user, Permission permission)
boolean	hasWriteAccess ()
User	getHost ()
boolean	isHost ()
void	addUser (User user)
void	userStartedQueuing (final User user)
void	userFinishedProjectNegotiation (final User user)
void	removeUser (User user)
void	kickUser (User user)
void	addListener (ISharedProjectListener listener)
void	removeListener (ISharedProjectListener listener)
Set< IProject >	getProjects ()
void	start ()
User	getUser (JID jid)
JID	getResourceQualifiedJID (JID jid)
User	getLocalUser ()
boolean	hasExclusiveWriteAccess ()
ConcurrentDocumentServer	getConcurrentDocumentServer ()
ConcurrentDocumentClient	getConcurrentDocumentClient ()
Set< Integer >	getUnavailableColors ()
void	exec (List< IActivity > activities)
void	addActivityProducer (IActivityProducer producer)
void	removeActivityProducer (IActivityProducer producer)
void	addActivityConsumer (IActivityConsumer consumer)
void	removeActivityConsumer (IActivityConsumer consumer)
List< User >	getUsersWithWriteAccess ()
List< User >	getUsersWithReadOnlyAccess ()
List< User >	getRemoteUsersWithReadOnlyAccess ()
boolean	userHasProject (User user, IProject project)
boolean	isShared (IResource resource)
boolean	isCompletelyShared (IProject project)
boolean	useVersionControl ()
String	getProjectID (IProject project)
IProject	getProject (String projectID)
void	addSharedResources (IProject project, String projectID, List< IResource > dependentResources)
List< IResource >	getSharedResources ()
Map< IProject, List< IResource > >	getProjectResourcesMapping ()
List< IResource >	getSharedResources (IProject project)
void	addProjectMapping (String projectID, IProject project)
void	removeProjectMapping (String projectID, IProject project)
StopManager	getStopManager ()
void	changeColor (int colorID)
void	enableQueuing (IProject project)
void	disableQueuing ()
String	getID ()
Object	getComponent (Object key)
Static Public Attributes
static final String	SESSION_CONNECTION_ID = "saros-main-session"

---

Detailed Description

A Saros session consists of one or more shared projects, which are the central concept of the Saros plugin. They are associated with projects and make them available for synchronous/real-time collaboration.

Author:

rdjemili

---

Member Function Documentation

void de.fu_berlin.inf.dpp.session.ISarosSession.addActivityConsumer

(

IActivityConsumer

consumer

)

Adds an IActivityConsumer so it will be called when an activity is to be executed locally.

Parameters:

consumer

The exec() method of this consumer will be called. "Consume" is not meant in a destructive way: all consumers will be called for every activity.

See also:

removeActivityConsumer(IActivityConsumer)

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.addActivityProducer

(

IActivityProducer

producer

)

Adds an IActivityProducer so the production of its activities will be noticed.

Parameters:

producer

The session will register an IActivityListener on this producer. It is expected that the producer will inform that listener about new activities via created().

See also:

removeActivityProducer(IActivityProducer)

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.addListener

(

ISharedProjectListener

listener

)

Adds the given shared project listener. This call is ignored if the listener is already a listener of this session.

Parameters:

listener

The listener that is to be added.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.addProjectMapping	(	String	projectID,
		IProject	project
	)

Stores a bidirectional mapping between project and projectID.

This information is necessary for receiving (unserializing) resource-related activities.

Parameters:

projectID	Session-wide ID of the project
project	the local representation of the project

See also:

removeProjectMapping(String, IProject)

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.addSharedResources	(	IProject	project,
		String	projectID,
		List< IResource >	dependentResources
	)

Adds the specified project and/or resources to this session.

Parameters:

project	The project to share.
projectID	The global project ID.
dependentResources	The project dependent resources.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.addUser

(

User

user

)

Adds the user to this session. If the session currently serves as host all other session users will be noticed about the new user.

Parameters:

user	the user that is to be added

void de.fu_berlin.inf.dpp.session.ISarosSession.changeColor

(

int

colorID

)

Changes the color for the current session. The color change is performed on the session host and may therefore result in a different color id.

Parameters:

colorID

the new color id that should be used during the session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.disableQueuing

(

)

FOR INTERNAL USE ONLY !

Disables queuing for all shared projects and flushes all queued activities.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.enableQueuing

(

IProject

project

)

FOR INTERNAL USE ONLY !

Starts queuing of incoming IResourceActivity project-related activities}, since they cannot be applied before their corresponding project is received and extracted.

That queuing relies on an existing project-to-projectID mapping (see addProjectMapping(String, IProject, JID)), otherwise incoming activities cannot be queued and will be lost.

Parameters:

project

the project for which project-related activities should be queued

See also:

disableQueuing()

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.exec

(

List< IActivity >

activities

)

FOR INTERNAL USE ONLY !

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

Object de.fu_berlin.inf.dpp.session.ISarosSession.getComponent

(

Object

key

)

Returns the session runtime component with the given key.

Parameters:

key	the key of the component

Returns:

the runtime component or null if the component is either not available or does not exists

Deprecated:

This method should be used with great care. It is up to to the caller to ensure that the returned reference can be garbage collected when the session has stopped

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

ConcurrentDocumentClient de.fu_berlin.inf.dpp.session.ISarosSession.getConcurrentDocumentClient

(

)

the concurrent document manager is responsible for all jupiter controlled documents

Returns:

the concurrent document manager

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

ConcurrentDocumentServer de.fu_berlin.inf.dpp.session.ISarosSession.getConcurrentDocumentServer

(

)

the concurrent document manager is responsible for all jupiter controlled documents

Returns:

the concurrent document manager

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

User de.fu_berlin.inf.dpp.session.ISarosSession.getHost

(

)

Returns the host of this session.

This method will always return the same value for this session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

String de.fu_berlin.inf.dpp.session.ISarosSession.getID

(

)

Returns the id of the current session.

Returns:

the id of the current session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

User de.fu_berlin.inf.dpp.session.ISarosSession.getLocalUser

(

)

Returns the local user of this session.

This method will always return the same value for this session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

IProject de.fu_berlin.inf.dpp.session.ISarosSession.getProject

(

String

projectID

)

Returns the project with the given ID.

Returns:

the project with the given ID or null if no project with this ID is shared

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

String de.fu_berlin.inf.dpp.session.ISarosSession.getProjectID

(

IProject

project

)

Returns the global ID of the project.

Returns:

the global ID of the project or null if this project is not shared

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

Map<IProject, List<IResource> > de.fu_berlin.inf.dpp.session.ISarosSession.getProjectResourcesMapping

(

)

Returns a map with the mapping of shared resources to their project.

Returns:

project-->resource mapping

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

Set<IProject> de.fu_berlin.inf.dpp.session.ISarosSession.getProjects

(

)

Returns:

the shared projects associated with this session, never null but may be empty

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<User> de.fu_berlin.inf.dpp.session.ISarosSession.getRemoteUsers

(

)

Returns:

a list of all remote users of this session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<User> de.fu_berlin.inf.dpp.session.ISarosSession.getRemoteUsersWithReadOnlyAccess

(

)

Returns all users in this project which are both remotely and have Permission#READONLY_ACCESS right now.

This is a snapshot copy. This list does not change if users' Permission change.

There is no guarantee that the users in this list will be part of the project after you exit the SWT thread context.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

JID de.fu_berlin.inf.dpp.session.ISarosSession.getResourceQualifiedJID

(

JID

jid

)

Given a JID (resource qualified or not), will return the resource qualified JID associated with this user or null if no user for the given JID exists in the session.

 E.g:
 
 JID rqJID = session.getResourceQualifiedJID(new JID("alice@foo.com");
 System.out.println(rqJID);
 
 

Will print out something like alice@foo.com/Saros*****

Parameters:

jid	the JID to retrieve the resource qualified JID for

Returns:

the resource qualified JID or null if no user is found with this JID

Deprecated:

Do not use this method in new code, ensure you can obtain a resource qualified JID and use getUser(JID) instead.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<IResource> de.fu_berlin.inf.dpp.session.ISarosSession.getSharedResources

(

)

Returns all shared resources in this session.

Returns:

a list of all shared resources (excluding projects) from this session.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<IResource> de.fu_berlin.inf.dpp.session.ISarosSession.getSharedResources

(

IProject

project

)

Returns the shared resources of the project in this session.

Parameters:

project

Returns:

the shared resources or null if this project is not or fully shared.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

StopManager de.fu_berlin.inf.dpp.session.ISarosSession.getStopManager

(

)

Return the stop manager of this session.

Returns:

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

Set<Integer> de.fu_berlin.inf.dpp.session.ISarosSession.getUnavailableColors

(

)

Returns a snapshot of the currently unavailable (in use) color ids.

Returns:

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

User de.fu_berlin.inf.dpp.session.ISarosSession.getUser

(

JID

jid

)

Given a resource qualified JID, this method will return the user which has the identical ID including resource.

Use getResourceQualifiedJID(JID) in the case if you do not know the RQ-JID.

Returns:

the user with the given fully qualified JID or null if not user with such a JID exists in the session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<User> de.fu_berlin.inf.dpp.session.ISarosSession.getUsers

(

)

Returns:

a list of all users of this session

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<User> de.fu_berlin.inf.dpp.session.ISarosSession.getUsersWithReadOnlyAccess

(

)

Returns a list of all users in this session have Permission#READONLY_ACCESS right now.

This is a snapshot copy. This list does not change if users' Permission change.

There is no guarantee that the users in this list will be part of the project after you exit the SWT thread context.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

List<User> de.fu_berlin.inf.dpp.session.ISarosSession.getUsersWithWriteAccess

(

)

Returns a list of all users in this session which have Permission#WRITE_ACCESS right now.

This is a snapshot copy. This list does not change if users' Permission change.

There is no guarantee that the users in this list will be part of the project after you exit the SWT thread context.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.hasExclusiveWriteAccess

(

)

Returns:

true, if there is exactly one user with Permission#WRITE_ACCESS, false otherwise.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.hasWriteAccess

(

)

Returns:

true if the local user has write access, false otherwise

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.initiatePermissionChange	(	User	user,
		Permission	newPermission
	)		throws CancellationException, InterruptedException

Initiates a Permission change.

This method may only called by the host. This method mustn't be called from the SWT UI thread

Returning after the Permission change is complete

Parameters:

user	The user whose Permission has to be changed
newPermission	The new Permission of the user

Exceptions:

CancellationException
InterruptedException

boolean de.fu_berlin.inf.dpp.session.ISarosSession.isCompletelyShared

(

IProject

project

)

Checks if selected project is a complete shared one or partial shared.

Parameters:

project

Returns:

true if complete, false if partial

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.isHost

(

)

Returns:

true if the local user is the host of this session, false otherwise.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.isShared

(

IResource

resource

)

Returns:

true if the given resource is currently shared in this session, false otherwise

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.kickUser

(

User

user

)

Kicks and removes the user out of the session.

Parameters:

user	the user that should be kicked from the session

Exceptions:

IllegalStateException	if the local user is not the host of the session
IllegalArgumentException	if the user to kick is the local user

void de.fu_berlin.inf.dpp.session.ISarosSession.removeActivityConsumer

(

IActivityConsumer

consumer

)

Removes an IActivityConsumer from the session

Parameters:

consumer

This consumer will no longer be called when an activity is to be executed locally.

See also:

addActivityConsumer(IActivityConsumer)

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.removeActivityProducer

(

IActivityProducer

producer

)

Removes an IActivityProducer from the session.

Parameters:

producer

The session will unregister its IActivityListener from this producer and it is expected that the producer no longer calls created().

See also:

addActivityProducer(IActivityProducer)

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.removeListener

(

ISharedProjectListener

listener

)

Removes the given shared project listener. This call is ignored if the listener does not belong to the current listeners of this session.

Parameters:

listener

the listener that is to be removed.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.removeProjectMapping	(	String	projectID,
		IProject	project
	)

Removes the bidirectional mapping project and projectId that was created by addProjectMapping() .

TODO Why is the project parameter needed here? This forces callers to store the mapping themselves (or retrieve it just before calling this method).

Parameters:

projectID	Session-wide ID of the project
project	the local representation of the project

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.removeUser

(

User

user

)

Removes a user from this session.

Parameters:

user	the user that is to be removed

void de.fu_berlin.inf.dpp.session.ISarosSession.setPermission	(	User	user,
		Permission	permission
	)

Set the Permission of the given user.

This method MUST to be called from the SWT UI thread

Parameters:

user	the user which Permission has to be set.
permission	The new Permission of the user.

void de.fu_berlin.inf.dpp.session.ISarosSession.start

(

)

FOR INTERNAL USE ONLY !

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.userFinishedProjectNegotiation

(

final User

user

)

Informs all participants and listeners that a user now has finished the Project Negotiation.

Parameters:

user

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.userHasProject	(	User	user,
		IProject	project
	)

Checks if the user is ready to process IResourceActivitys for a given project

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

void de.fu_berlin.inf.dpp.session.ISarosSession.userStartedQueuing

(

final User

user

)

Informs all listeners that a user now has Projects and can process IResourceActivitys.

This method may only called by the host.

Parameters:

user

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

boolean de.fu_berlin.inf.dpp.session.ISarosSession.useVersionControl

(

)

Returns true if VCS support is enabled for this session.

This setting can be changed in the Preferences. VCS support can be disabled during a running session, but enabling VCS support doesn't have any effect.

Returns:

true if this session uses Version Control, otherwise false.

Implemented in de.fu_berlin.inf.dpp.project.internal.SarosSession, and de.fu_berlin.inf.dpp.core.project.internal.SarosSession.

---

Member Data Documentation

final String de.fu_berlin.inf.dpp.session.ISarosSession.SESSION_CONNECTION_ID = "saros-main-session" [static]

3, Architecture Overview, Session Management:

This Interface is the main entrance Point for the "Session Management"-Component. The Session Management is responsible for managing a Session and keeping the shared projects in a consistent state across the local copies of all participants. It functions as the core component in a running session and directs communication between all other components. In general this component takes input from the User Interface, processes it and afterwards passes the result to the Network Layer. Connection identifier to use for sending data. See ITransmitter#sendToSessionUser