net.java.sip.communicator.service.protocol
Interface WhiteboardSession

All Known Implementing Classes:

WhiteboardSessionJabberImpl

public interface WhiteboardSession

A represenation of a WhiteboardSession.

Author:

Julien Waechter, Emil Ivov

Method Summary

void	addWhiteboardChangeListener(WhiteboardChangeListener listener) Adds a whiteboard change listener to this whiteboard so that it could receive events on new whiteboard participants, theme changes and others.
void	addWhiteboardObjectListener(WhiteboardObjectListener listener) Registers listener so that it would receive events every time a new WhiteboardObject is received on this whiteboard.
void	addWhiteboardParticipant(WhiteboardParticipant wbParticipant) Adds wbParticipant to the list of participants in this whiteboard.
WhiteboardObject	createWhiteboardObject(String name) Create a WhiteboardObject instance with the specified type.
void	deleteWhiteboardObject(WhiteboardObject obj) Sends a WhiteboardObject to delete and delete the local WhiteboardObject
ProtocolProviderService	getProtocolProvider() Returns a reference to the ProtocolProviderService instance that created this whiteboard.
WhiteboardSessionState	getState() Returns the state that this whiteboard is currently in.
String[]	getSupportedWhiteboardObjects() Returns all the type of WhiteboardObject that this whiteboard support.
String	getWhiteboardID() Returns the id of the specified Whiteboard.
Vector<WhiteboardObject>	getWhiteboardObjects() Returns the WhiteboardObjects in this whiteboard session.
Iterator<WhiteboardParticipant>	getWhiteboardParticipants() Returns an iterator over all whiteboard participants.
int	getWhiteboardParticipantsCount() Returns the number of participants currently associated with this whiteboard session.
void	invite(String userAddress) Invites another user to this room.
boolean	isJoined() Returns true if the local user is currently in the whiteboard session (after whiteboarding one of the join() methods).
void	join() Joins this whiteboard with the nickname of the local user so that the user would start receiving events and WhiteboardObject for it.
void	join(byte[] password) Joins this whiteboard so that the user would start receiving events and WhiteboardObject for it.
void	leave() Leave this whiteboard.
void	moveWhiteboardObject(WhiteboardObject obj) Sends a WhiteboardObject to modify and modifies the local WhiteboardObject
void	removeWhiteboardChangeListener(WhiteboardChangeListener listener) Removes listener to this whiteboard so that it won't receive further WhiteboardChangeEvents.
void	removeWhiteboardObjectListener(WhiteboardObjectListener listener) Removes listener so that it won't receive any further WhiteboardObject events from this room.
void	removeWhiteboardParticipant(WhiteboardParticipant wbParticipant) Removes whiteboardParticipant from the list of participants in this whiteboard.
void	sendWhiteboardObject(WhiteboardObject obj) Resolves obj with the other session participants.
void	setState(WhiteboardSessionState newState) Sets the state of this whiteboard

Method Detail

getWhiteboardID

String getWhiteboardID()

Returns the id of the specified Whiteboard.

Returns:

a String uniquely identifying the whiteboard.

getWhiteboardParticipants

Iterator<WhiteboardParticipant> getWhiteboardParticipants()

Returns an iterator over all whiteboard participants.

Returns:

an Iterator over all participants currently involved in the whiteboard.

getWhiteboardParticipantsCount

int getWhiteboardParticipantsCount()

Returns the number of participants currently associated with this whiteboard session.

Returns:

an int indicating the number of participants currently associated with this whiteboard.

addWhiteboardChangeListener

void addWhiteboardChangeListener(WhiteboardChangeListener listener)

Adds a whiteboard change listener to this whiteboard so that it could receive events on new whiteboard participants, theme changes and others.

Parameters:

listener - the listener to register

removeWhiteboardChangeListener

void removeWhiteboardChangeListener(WhiteboardChangeListener listener)

Removes listener to this whiteboard so that it won't receive further WhiteboardChangeEvents.

Parameters:

listener - the listener to register

getProtocolProvider

ProtocolProviderService getProtocolProvider()

Returns a reference to the ProtocolProviderService instance that created this whiteboard.

Returns:

a reference to the ProtocolProviderService instance that created this whiteboard.

join

void join()
          throws OperationFailedException

Joins this whiteboard with the nickname of the local user so that the user would start receiving events and WhiteboardObject for it.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

join

void join(byte[] password)
          throws OperationFailedException

Joins this whiteboard so that the user would start receiving events and WhiteboardObject for it. The method uses the nickname of the local user and the specified password in order to enter the whiteboard session.

Parameters:

password - the password to use when authenticating on the whiteboard session.

Throws:

OperationFailedException - with the corresponding code if an error occurs while joining the room.

isJoined

boolean isJoined()

Returns true if the local user is currently in the whiteboard session (after whiteboarding one of the join() methods).

Returns:

true if currently we're currently in this whiteboard and false otherwise.

leave

void leave()

Leave this whiteboard. Once this method is whiteboarded, the user won't be listed as a member of the whiteboard any more and no further whiteboard events will be delivered. Depending on the underlying protocol and implementation leave() might cause the room to be destroyed if it has been created by the local user.

invite

void invite(String userAddress)

Invites another user to this room.

If the room is password-protected, the invitee will receive a password to use to join the room. If the room is members-only, the the invitee may be added to the member list.

Parameters:

userAddress - the address of the user to invite to the room. (one may also invite users not on their contact list).

addWhiteboardObjectListener

void addWhiteboardObjectListener(WhiteboardObjectListener listener)

Registers listener so that it would receive events every time a new WhiteboardObject is received on this whiteboard.

Parameters:

listener - a WhiteboardObjectListener that would be notified every time a new WhiteboardObject is received on this whiteboard.

removeWhiteboardObjectListener

void removeWhiteboardObjectListener(WhiteboardObjectListener listener)

Removes listener so that it won't receive any further WhiteboardObject events from this room.

Parameters:

listener - the WhiteboardObjectListener to remove from this room

createWhiteboardObject

WhiteboardObject createWhiteboardObject(String name)

Create a WhiteboardObject instance with the specified type. This method only creates the object locally and it would not be visible to other session participants until it is resolved with the sendWhiteboardObject(WhiteboardObject) method.

Parameters:

name - the name of the object to create (should be one of the + * WhiteboardObjectXXX.NAME fields).

Returns:

the newly created WhiteboardObject with an id

sendWhiteboardObject

void sendWhiteboardObject(WhiteboardObject obj)
                          throws OperationFailedException

Resolves obj with the other session participants. When called for the first time with a specific WhiteboardObject instance it would appear on their whiteboards. If obj has already been sent through this method previously, this method would result in updating the way the object looks in other instances of this session (i.e. the method should be used for both initially sending an object as well as sending changes made on an object since the method was last called).

Parameters:

obj - the WhiteboardObject to send.

Throws:

OperationFailedException - if sending the WhiteboardObject fails for some reason.

moveWhiteboardObject

void moveWhiteboardObject(WhiteboardObject obj)
                          throws OperationFailedException

Sends a WhiteboardObject to modify and modifies the local WhiteboardObject

Parameters:

obj - the WhiteboardObject to send and modify

Throws:

OperationFailedException - if sending the WhiteboardObject fails for some reason.

deleteWhiteboardObject

void deleteWhiteboardObject(WhiteboardObject obj)
                            throws OperationFailedException

Sends a WhiteboardObject to delete and delete the local WhiteboardObject

Parameters:

obj - the WhiteboardObject to send and delete

Throws:

OperationFailedException - if sending the WhiteboardObject fails for some reason.

addWhiteboardParticipant

void addWhiteboardParticipant(WhiteboardParticipant wbParticipant)

Adds wbParticipant to the list of participants in this whiteboard. If the wb participant is already included in the whiteboard, the method has no effect.

Parameters:

wbParticipant - the new WhiteboardParticipant

removeWhiteboardParticipant

void removeWhiteboardParticipant(WhiteboardParticipant wbParticipant)

Removes whiteboardParticipant from the list of participants in this whiteboard. The method has no effect if there was no such participant in the whiteboard.

Parameters:

wbParticipant - the WhiteboardParticipant leaving the whiteboard;

getWhiteboardObjects

Vector<WhiteboardObject> getWhiteboardObjects()

Returns the WhiteboardObjects in this whiteboard session.

Returns:

an Vector of WhiteboardObjects associated with this whiteboard.

setState

void setState(WhiteboardSessionState newState)

Sets the state of this whiteboard

Parameters:

newState - a reference to the WhiteboardState instance that the whiteboard is to enter.

getState

WhiteboardSessionState getState()

Returns the state that this whiteboard is currently in.

Returns:

a reference to the WhiteboardState instance that the whiteboard is currently in.

getSupportedWhiteboardObjects

String[] getSupportedWhiteboardObjects()

Returns all the type of WhiteboardObject that this whiteboard support.

Returns:

all the WhiteboardObject supported by this WhiteboardSession.