whiteboard operation set and services

cusax-fix
Yana Stamcheva 18 years ago
parent c079667397
commit 3f756e0455

@ -6,10 +6,12 @@
*/
package net.java.sip.communicator.service.protocol;
import java.util.*;
import net.java.sip.communicator.service.protocol.event.*;
/**
* Provides basic functionality for whiteboard.
* Provides basic functionality for white-board.
*
* @author Julien Waechter
*/
@ -17,29 +19,141 @@ public interface OperationSetWhiteboarding
extends OperationSet
{
/**
* Create a new whiteboard session and invite the specified Contact to
* join it.
* Returns a list of the <tt>WhiteboardSession</tt>s that we have joined and
* are currently active in.
*
* @return a <tt>List</tt> of the <tt>WhiteboardSession</tt>s where the user
* has joined using a given connection.
*/
public List getCurrentlyJoinedWhiteboards();
/**
* Returns a list of the <tt>WhiteboardSession</tt>s that
* <tt>WhiteboardParticipant</tt> has joined and is currently active in.
*
* @param whiteboardContact the address of the contact that we'd like to
* invite to a our new whiteboard session.
* @param participant the participant whose current
* <tt>WhiteboardSession</tt>s we will be querying.
* @return a list of the <tt>WhiteboardSession</tt>s that
* <tt>WhiteboardParticipant</tt> has joined and is currently active in.
*
* @return WhiteboardSession the newly WhiteboardParticipant
* @throws OperationFailedException if an error occurs while trying to
* discover the session.
* @throws OperationNotSupportedException if the server does not support
* white-boarding
*/
public List getCurrentlyJoinedWhiteboards(WhiteboardParticipant participant)
throws OperationFailedException, OperationNotSupportedException;
/**
* Creates a <tt>WhiteboardSession</tt> with the name <tt>sessionName</tt>
* and according to the specified <tt>sessionProperties</tt>. When the
* method returns the white-board session object, the local user will not
* have joined it and thus will not receive messages on it until the
* <tt>WhiteboardSession.join()</tt> method is called.
* <p>
* @param sessionName the name of the <tt>WhiteboardSession</tt> to create.
* @param sessionProperties properties specifying how the session should be
* created.
* @throws OperationFailedException if the room couldn't be created for some
* reason (e.g. room already exists; user already joined to an existent
* room or user has no permissions to create a chat room).
* @throws OperationNotSupportedException if chat room creation is not
* supported by this server
*
* @throws OperationFailedException with the corresponding code if we fail
* to create the whiteboard.
* @return the newly created <tt>WhiteboardSession</tt> named
* <tt>sessionName</tt>.
*/
public WhiteboardSession createWhiteboardSession (Contact whiteboardContact)
throws OperationFailedException;
public WhiteboardSession createWhiteboardSession(
String sessionName,
Hashtable sessionProperties)
throws OperationFailedException, OperationNotSupportedException;
/**
* Closes the specified <tt>whiteboardSession</tt> and destroys all objects
* and states associated with it.
* Returns a reference to a <tt>WhiteboardSession</tt> named
* <tt>sessionName</tt> or null if no such session exists.
* <p>
* @param sessionName the name of the <tt>WhiteboardSession</tt> that we're
* looking for.
* @return the <tt>WhiteboardSession</tt> named <tt>sessionName</tt> or null
* if no such session exists on the server that this provider is currently
* connected to.
*
* @param whiteboardSession the session that we'd like to end.
* @throws OperationFailedException if an error occurs while trying to
* discover the white-board session on the server.
* @throws OperationNotSupportedException if the server does not support
* white-boarding
*/
public WhiteboardSession findWhiteboardSession(String sessionName)
throws OperationFailedException, OperationNotSupportedException;
/**
* Informs the sender of an invitation that we decline their invitation.
*
* @param invitation the invitation we are rejecting.
* @param rejectReason the reason to reject the invitation (optional)
*/
public void rejectInvitation(WhiteboardInvitation invitation,
String rejectReason);
/**
* Adds a listener to invitation notifications. The listener will be fired
* anytime an invitation is received.
*
* @param listener an invitation listener.
*/
public void addInvitationListener(WhiteboardInvitationListener listener);
/**
* Removes <tt>listener</tt> from the list of invitation listeners
* registered to receive invitation events.
*
* @throws OperationFailedException with the corresponding code if we fail
* to finish the whiteboard.
* @param listener the invitation listener to remove.
*/
public void removeInvitationListener(WhiteboardInvitationListener listener);
/**
* Adds a listener to invitation notifications. The listener will be fired
* anytime an invitation is received.
*
* @param listener an invitation listener.
*/
public void addInvitationRejectionListener(
WhiteboardInvitationRejectionListener listener);
/**
* Removes the given listener from the list of invitation listeners
* registered to receive events every time an invitation has been rejected.
*
* @param listener the invitation listener to remove.
*/
public void removeInvitationRejectionListener(
WhiteboardInvitationRejectionListener listener);
/**
* Returns true if <tt>contact</tt> supports white-board sessions.
*
* @param contact reference to the contact whose support for white-boards
* we are currently querying.
* @return a boolean indicating whether <tt>contact</tt> supports
* white-boards.
*/
public boolean isWhiteboardingSupportedByContact(Contact contact);
/**
* Adds a listener that will be notified of changes in our participation in
* a white-board session such as us being joined, left, dropped.
*
* @param listener a local user participation listener.
*/
public void addPresenceListener(
WhiteboardSessionPresenceListener listener);
/**
* Removes a listener that was being notified of changes in our
* participation in a room such as us being kicked, joined, left.
*
* @param listener a local user participation listener.
*/
public void endWhiteboardSession (WhiteboardSession whiteboardSession)
throws OperationFailedException;
public void removePresenceListener(
WhiteboardSessionPresenceListener listener);
}

@ -0,0 +1,51 @@
/*
* SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package net.java.sip.communicator.service.protocol;
/**
* This interface represents an invitation, which is send from a whiteboard
* participant to another user in order to invite this user to join the
* whiteboard.
*
* @author Yana Stamcheva
*/
public interface WhiteboardInvitation
{
/**
* Returns the <tt>WhiteboardSession</tt>, which is the target of this
* invitation.
* The whiteboard returned by this method will be the one to which the user
* is invited to join to.
*
* @return the <tt>WhiteboardSession</tt>, which is the target of this
* invitation
*/
public WhiteboardSession getTargetWhiteboard();
/**
* Returns the password to use when joining the whiteboard.
*
* @return the password to use when joining the whiteboard
*/
public byte[] getWhiteboardPassword();
/**
* Returns the <tt>WhiteboardParticipant</tt> that sent this invitation.
*
* @return the <tt>WhiteboardParticipant</tt> that sent this invitation.
*/
public String getInviter();
/**
* Returns the reason of this invitation, or null if there is no reason
* specified.
*
* @return the reason of this invitation, or null if there is no reason
* specified
*/
public String getReason();
}

@ -1,214 +0,0 @@
/*
* SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package net.java.sip.communicator.service.protocol;
import java.util.*;
/**
* Used to access the content of instant whiteboard objects that are sent or
* received via the WhiteboardOperationSet.
* <p>
* WhiteboardObject are created through the <tt>WhiteboardSession</tt> session.
* <p>
*
* All WhiteboardObjects have whiteboard object id.
*
* @author Julien Waechter
* @author Emil Ivov
*/
public interface WhiteboardObject
{
/**
* A type string constant indicating that an object is of type binary image.
*/
public static final String TYPE_IMAGE = "IMAGE";
/**
* A type string constant indicating that an object is of type rectangle.
*/
public static final String TYPE_RECT = "RECT";
/**
* A type string constant indicating that an object is of type circle.
*/
public static final String TYPE_CIRCLE = "CIRCLE";
/**
* A type string constant indicating that an object is of type binary line.
*/
public static final String TYPE_LINE = "LINE";
/**
* A type string constant indicating that an object is of type polyline.
*/
public static final String TYPE_POLYLINE = "POLYLINE";
/**
* A type string constant indicating that an object is of type binary
* plygon.
*/
public static final String TYPE_POLYGON = "POLYGON";
/**
* A type string constant indicating that an object is of type elipse.
*/
public static final String TYPE_ELLIPSE = "ELLIPSE";
/**
* A type string constant indicating that an object is of type path.
*/
public static final String TYPE_PATH = "PATH";
/**
* A type string constant indicating that an object is of type text.
*/
public static final String TYPE_TEXT = "TEXT";
/**
* Returns a String uniquely identifying this WhiteboardObject.
*
* @return a String that uniquely identifies this WhiteboardObject.
*/
public String getID ();
/**
* Returns the type of this object. Currently this service defines
* a limited set of types (i.e. the TYPE_XXX constants defined above) that
* may be extended in the future.
*
* @return one of the TYPE_XXX constants defined by this interface,
* indicating the type of this whiteboard object.
*/
public String getType ();
/**
* Returns an integer indicating the thickness (represented as number of
* pixels) of this whiteboard object (or its border).
*
* @return the thickness (in pixels) of this object (or its border).
*/
public int getThickness ();
/**
* Sets the thickness (in pixels) of this whiteboard object.
*
* @param thickness the number of pixels that this object (or its border)
* should be thick.
*/
public void setThickness (int thickness);
/**
* Returns an integer representing the color of this object. The return
* value uses standard RGB encoding: bits 24-31 are alpha, 16-23 are red,
* 8-15 are green, 0-7 are blue.
*
* @return the RGB value of the color of this object.
*/
public int getColor ();
/**
* Sets the color of this whiteboard object (or rather it's border). The
* color parameter must be encoded with standard RGB encoding: bits 24-31
* are alpha, 16-23 are red, 8-15 are green, 0-7 are blue.
*
* @param color the color that we'd like to set on this object (using
* standard RGB encoding).
*/
public void setColor (int color);
/**
* Returns a list of all the <tt>WhiteboardPoint</tt> instances that this
* <tt>WhiteboardObject</tt> is composed of.
*
* @return the list of <tt>WhiteboardPoint</tt>s composing this object.
*/
public List getPoints ();
/**
* Sets the list of <tt>WhiteboardPoint</tt> instances that this
* <tt>WhiteboardObject</tt> is composed of.
*
* @param points the list of <tt>WhiteboardPoint</tt> instances that this
* <tt>WhiteboardObject</tt> is composed of.
*/
public void setPoints(List points);
/**
* Specifies an image that should be displayed as the background of this
* object.
*
* @param background a binary array containing the image that should be
* displayed as the object background.
*/
public void setBackgroundImage(byte[] background);
/**
* Returns a binary array containing the image that should be displayed as
* the background of this <tt>WhiteboardObject</tt>.
*
* @return a binary array containing the image that should be displayed as
* the object background.
*/
public byte[] getBackgroundImage();
/**
* Specifies the background color for this object. The color parameter
* must be encoded with standard RGB encoding: bits 24-31 are alpha, 16-23
* are red, 8-15 are green, 0-7 are blue.
*
* @param color the color that we'd like to set for the background of this
* <tt>WhiteboardObject</tt> (using standard RGB encoding).
*/
public void setBackgroundColor(int color);
/**
* Returns an integer representing the background color of this object. The
* return value uses standard RGB encoding: bits 24-31 are alpha, 16-23 are
* red, 8-15 are green, 0-7 are blue.
*
* @return the RGB value of the background color of this object.
*/
public int getBackgroundColor();
/**
* Sets <tt>value</tt> as the value of the <tt>key</tt> attribute.
*
* @param key the name of the attribute that we'd like to set.
* @param value value to be associated with the specified key
*/
public void addAttribute (String key, String value);
/**
* Returns the value to which the specified key is mapped, or null if this
* map contains no value for the key.
*
* @param key the key the value of which we'd like to retrieve.
*
* @return the value associated with <tt>key</tt>, or <tt>null</tt>
* if there was no such key.
*/
public String getAttribute (String key);
/**
* Returns a <tt>HashMap</tt> containing all attributes currently set for
* this <tt>WhiteboardObject</tt>.
*
* @return a <tt>HashMap</tt> mapping attribute keys to values for all
* attributes currently set for this <tt>WhiteboardObject</tt>.
*/
public HashMap getAttributes ();
/**
* Sets map as the complete set of attributes available for this
* <tt>WhiteboardObject</tt>. Any existing attributes will be removed prior
* to setting the new map.
*
* @param map the complete map of attributes defined for this
* <tt>WhiteboardObject</tt>.
*/
public void setAttributes (HashMap map);
}

@ -9,7 +9,8 @@
import net.java.sip.communicator.service.protocol.event.*;
/**
* The WhiteboardParticipant is an interface that represents participants in a whiteboard.
* The WhiteboardParticipant is an interface that represents participants in a
* whiteboard.
*
* @author Julien Waechter
* @author Emil Ivov

@ -6,6 +6,8 @@
*/
package net.java.sip.communicator.service.protocol;
import java.awt.geom.*;
/**
* A point representing a location in {@code (x,y)} coordinate space,
* specified in integer precision.
@ -71,6 +73,26 @@ public double getY()
return y;
}
/**
* Sets a new value to the x coordinate.
*
* @param y the new value of the x coordinate
*/
public void setX(double x)
{
this.x = x;
}
/**
* Sets a new value to the y coordinate.
*
* @param y the new value of the y coordinate
*/
public void setY(double y)
{
this.y = y;
}
/**
* Determines whether or not two points are equal. Two instances of
* <tt>WhiteboardPoint</tt> are equal if the values of their
@ -119,4 +141,17 @@ protected Object clone()
return new WhiteboardPoint(this);
}
/**
* Calculates the distance from this point the given point.
*
* @param p the point to which to calculate the distance
* @return the distance between this point and the given point
*/
public double distance(WhiteboardPoint p)
{
double PX = p.getX() - this.getX();
double PY = p.getY() - this.getY();
return Math.sqrt(PX * PX + PY * PY);
}
}

@ -10,6 +10,8 @@
import net.java.sip.communicator.service.protocol.event.*;
import net.java.sip.communicator.service.protocol.whiteboardobjects.WhiteboardObject;
/**
* A represenation of a <tt>WhiteboardSession</tt>.
*
@ -24,7 +26,7 @@ public interface WhiteboardSession
*
* @return a String uniquely identifying the whiteboard.
*/
public String getWhiteboardID();
public String getWhiteboardID ();
/**
* Returns an iterator over all whiteboard participants.
@ -32,7 +34,7 @@ public interface WhiteboardSession
* @return an Iterator over all participants currently involved in the
* whiteboard.
*/
public Iterator getWhiteboardParticipants();
public Iterator getWhiteboardParticipants ();
/**
* Returns the number of participants currently associated
@ -41,7 +43,7 @@ public interface WhiteboardSession
* @return an <tt>int</tt> indicating the number of participants currently
* associated with this whiteboard.
*/
public int getWhiteboardParticipantsCount();
public int getWhiteboardParticipantsCount ();
/**
* Adds a whiteboard change listener to this whiteboard so that it could
@ -49,7 +51,7 @@ public interface WhiteboardSession
*
* @param listener the listener to register
*/
public void addWhiteboardChangeListener(WhiteboardChangeListener listener);
public void addWhiteboardChangeListener (WhiteboardChangeListener listener);
/**
* Removes <tt>listener</tt> to this whiteboard so that it won't receive
@ -57,8 +59,8 @@ public interface WhiteboardSession
*
* @param listener the listener to register
*/
public void removeWhiteboardChangeListener(
WhiteboardChangeListener listener);
public void removeWhiteboardChangeListener (
WhiteboardChangeListener listener);
/**
* Returns a reference to the <tt>ProtocolProviderService</tt> instance
@ -67,7 +69,7 @@ public void removeWhiteboardChangeListener(
* @return a reference to the <tt>ProtocolProviderService</tt> instance that
* created this whiteboard.
*/
public ProtocolProviderService getProtocolProvider();
public ProtocolProviderService getProtocolProvider ();
/**
* Joins this whiteboard with the nickname of the local user so that the
@ -76,7 +78,7 @@ public void removeWhiteboardChangeListener(
* @throws OperationFailedException with the corresponding code if an error
* occurs while joining the room.
*/
public abstract void join() throws OperationFailedException;
public abstract void join () throws OperationFailedException;
/**
* Joins this whiteboard so that the user would start receiving events and
@ -88,16 +90,16 @@ public void removeWhiteboardChangeListener(
* @throws OperationFailedException with the corresponding code if an error
* occurs while joining the room.
*/
public abstract void join(byte[] password) throws OperationFailedException;
public abstract void join (byte[] password) throws OperationFailedException;
/**
* Returns true if the local user is currently in the whiteboard session
* (after whiteboarding one of the {@link #join()} methods).
* (after whiteboarding one of the {@link #join(String)} methods).
*
* @return true if currently we're currently in this whiteboard and false
* otherwise.
*/
public abstract boolean isJoined();
public abstract boolean isJoined ();
/**
* Leave this whiteboard. Once this method is whiteboarded, the user won't
@ -106,8 +108,7 @@ public void removeWhiteboardChangeListener(
* and implementation leave() might cause the room to be destroyed if it has
* been created by the local user.
*/
public abstract void leave();
public abstract void leave ();
/**
* Invites another user to this room.
@ -119,8 +120,7 @@ public void removeWhiteboardChangeListener(
* @param userAddress the address of the user to invite to the room.
* (one may also invite users not on their contact list).
*/
public abstract void invite(String userAddress);
public abstract void invite (String userAddress);
/**
* Registers <tt>listener</tt> so that it would receive events every time a
@ -131,7 +131,7 @@ public void removeWhiteboardChangeListener(
* notified every time a new WhiteboardObject
* is received on this whiteboard.
*/
public abstract void addWhiteboardObjectListener(
public abstract void addWhiteboardObjectListener (
WhiteboardObjectListener listener);
/**
@ -142,7 +142,7 @@ public abstract void addWhiteboardObjectListener(
* @param listener the <tt>WhiteboardObjectListener</tt>
* to remove from this room
*/
public abstract void removeWhiteboardObjectListener(
public abstract void removeWhiteboardObjectListener (
WhiteboardObjectListener listener);
/**
@ -151,12 +151,12 @@ public abstract void removeWhiteboardObjectListener(
* session participants until it is resolved with the
* sendWhiteboardObject(WhiteboardObject) method.
*
* @param type the type of the object to create (should be one of the
* WhiteboardObject.TYPE_XXX fields).
* @param name the name of the object to create (should be one of the
+ * WhiteboardObjectXXX.NAME fields).
*
* @return the newly created WhiteboardObject with an id
*/
public abstract WhiteboardObject createWhiteboardObject(String type);
public abstract WhiteboardObject createWhiteboardObject(String name);
/**
* Resolves <tt>obj</tt> with the other session participants. When called
@ -171,17 +171,29 @@ public abstract void removeWhiteboardObjectListener(
* @throws OperationFailedException if sending the WhiteboardObject fails
* for some reason.
*/
public abstract void sendWhiteboardObject(WhiteboardObject obj)
public abstract void sendWhiteboardObject (WhiteboardObject obj)
throws OperationFailedException;
/**
* Sends the <tt>obj</tt>
* Sends a <tt>WhiteboardObject</tt> to modify
* and modifies the local <tt>WhiteboardObject</tt>
*
* @param obj the <tt>WhiteboardObject</tt> to send.
* @param obj the <tt>WhiteboardObject</tt> to send and modify
* @throws OperationFailedException if sending
* the WhiteboardObject fails for some reason.
*/
public abstract void moveWhiteboardObject (WhiteboardObject obj)
throws OperationFailedException;
/**
* Sends a <tt>WhiteboardObject</tt> to delete
* and delete the local <tt>WhiteboardObject</tt>
*
* @param obj the <tt>WhiteboardObject</tt> to send and delete
* @throws OperationFailedException if sending
* the WhiteboardObject fails for some reason.
*/
public abstract void moveWhiteboardObject(WhiteboardObject obj)
public abstract void deleteWhiteboardObject (WhiteboardObject obj)
throws OperationFailedException;
/**
@ -192,8 +204,8 @@ public abstract void moveWhiteboardObject(WhiteboardObject obj)
*
* @param wbParticipant the new <tt>WhiteboardParticipant</tt>
*/
public abstract void addWhiteboardParticipant(
WhiteboardParticipant wbParticipant);
public abstract void addWhiteboardParticipant (
WhiteboardParticipant wbParticipant);
/**
* Removes <tt>whiteboardParticipant</tt> from the list of participants in
@ -203,14 +215,16 @@ public abstract void addWhiteboardParticipant(
* @param wbParticipant the <tt>WhiteboardParticipant</tt> leaving the
* whiteboard;
*/
public abstract void removeWhiteboardParticipant(
WhiteboardParticipant wbParticipant);
public abstract void removeWhiteboardParticipant (
WhiteboardParticipant wbParticipant);
/**
* Returns the WhiteboardObjects in this whiteboard session.
* @return an <tt>Vector</tt> of WhiteboardObjects associated
* with this whiteboard.
*/
public Vector getWhiteboardObjects();
public Vector getWhiteboardObjects ();
/**
* Sets the state of this whiteboard
@ -218,12 +232,20 @@ public abstract void removeWhiteboardParticipant(
* @param newState a reference to the <tt>WhiteboardState</tt> instance that
* the whiteboard is to enter.
*/
public void setState(WhiteboardSessionState newState);
public void setState (WhiteboardSessionState newState);
/**
* Returns the state that this whiteboard is currently in.
*
* @return a reference to the <tt>WhiteboardState</tt> instance
* that the whiteboard is currently in.
*/
public WhiteboardSessionState getState();
public WhiteboardSessionState getState ();
/**
* Returns all the type of WhiteboardObject that this whiteboard support.
*
* @return all the WhiteboardObject supported by this WhiteboardSession.
*/
public String[] getSupportedWhiteboardObjects();
}

@ -12,4 +12,5 @@ Export-Package: net.java.sip.communicator.service.protocol,
net.java.sip.communicator.service.protocol.jabberconstants,
net.java.sip.communicator.service.protocol.msnconstants,
net.java.sip.communicator.service.protocol.yahooconstants,
net.java.sip.communicator.service.protocol.event
net.java.sip.communicator.service.protocol.event,
net.java.sip.communicator.service.protocol.whiteboardobjects

Loading…
Cancel
Save