com.sun.im.service
Interface Conference

All Known Subinterfaces:
NewsChannel

public interface Conference

A Conference is an instant messaging session between 2 or more users.


Field Summary
static int INVITE
          ability to invite a non-member to become a member to a chat room.
static int LISTEN
          The LISTEN operation is the ability to join the chat room as a passive user.
static int MANAGE
          the MANAGE operation set includes shutting down the conference or bulletin board, or modify other members' access right to this conference or bulletin board.
static int NONE
          No rights.
static int PUBLISH
          ability to send messages
static int STATUS_APPROVED
          A status indicating that the message was approved by the moderator
static int STATUS_MODIFIED
          A status indicating that the message was modified by the moderator
static int STATUS_PENDING
          A status indicating that the message was pending for moderation
static int STATUS_REJECTED
          A status indicating that the message was rejected by the moderator
static int STATUS_SUBMIT
          A status indicating that the message was submitted for moderation
 
Method Summary
 void addMessage(Message message)
          add a message, which will be received by other parties in the conference.
 void addModeratedMessage(Message message, int status, java.lang.String reason)
          This method should be used submit and approve moderated messages.
 void close()
          terminates the conference This will have the effect of destroying all currently archived messages (for a bulletin board) and unsubscribing all current subscribe members.
 InviteMessage createInviteMessage()
          create an invite message
 Message createMessage()
          create a new message
 int getDefaultPrivilege()
          return the conference's default access level
 java.lang.String getDestination()
          returns the conference's address.
 java.lang.String getDisplayName()
          returns the conference display name
 int getEventMask()
          get access levels for which conference events are generated.
 java.util.Collection getParticipants()
          Lists the participants in the room.
 int getPrivilege()
          return the current user's access level
 int getPrivilege(java.lang.String uid)
           
 java.lang.String getProperty(java.lang.String attribute)
          get a conference property
 boolean hasPrivilege(int accessLevel)
          checks if the user has the required privilege for this conference.
 void invite(int accessLevel, Message message, InviteMessageStatusListener listener)
          invite another user to this conference.
 boolean isPublic()
          Tells whether this conference is public or persistent.
 void join(ConferenceListener listener)
          invoked by the application to specify that the user accepts the conference and to pass the conference listener.
 void join(java.lang.String nick, ConferenceHistory history, ConferenceListener listener)
          invoked by the application to specify that the user accepts the conference and to pass the conference listener and a nick name.
 void leave()
          leave the conference.
 java.util.Map listPrivileges()
          get the privileges of the all the users affiliated with the bulletin board
 void moderate(boolean start)
          Start or stop the moderation
 void save()
          commit the current configuration to the server's persistent store.
 void setDefaultPrivilege(int accessLevel)
          set the default access level for members, unless specified otherwise.
 void setDisplayName(java.lang.String name)
          sets the display name.
 void setEventMask(int mask)
          Sets access levels for which conference events are generated.
 void setPrivilege(java.lang.String uid, int accessLevel)
          set a principal's privilege for this conference.
 void setPrivileges(java.util.Map map)
          sets the privleges of the users to the conference on the server
 void setProperty(java.lang.String attribute, java.lang.String value)
          set a conference property
 

Field Detail

NONE

public static final int NONE
No rights. Giving a member this access level is used to kick this member out.

See Also:
Constant Field Values

LISTEN

public static final int LISTEN
The LISTEN operation is the ability to join the chat room as a passive user.

See Also:
Constant Field Values

PUBLISH

public static final int PUBLISH
ability to send messages

See Also:
Constant Field Values

INVITE

public static final int INVITE
ability to invite a non-member to become a member to a chat room. The access level of invitees may not exceed that of the invitor.

See Also:
Constant Field Values

MANAGE

public static final int MANAGE
the MANAGE operation set includes shutting down the conference or bulletin board, or modify other members' access right to this conference or bulletin board. The MANAGE access right is initially given only to the creator of the conference or bulletin board.

See Also:
Constant Field Values

STATUS_SUBMIT

public static final int STATUS_SUBMIT
A status indicating that the message was submitted for moderation

See Also:
Constant Field Values

STATUS_PENDING

public static final int STATUS_PENDING
A status indicating that the message was pending for moderation

See Also:
Constant Field Values

STATUS_APPROVED

public static final int STATUS_APPROVED
A status indicating that the message was approved by the moderator

See Also:
Constant Field Values

STATUS_MODIFIED

public static final int STATUS_MODIFIED
A status indicating that the message was modified by the moderator

See Also:
Constant Field Values

STATUS_REJECTED

public static final int STATUS_REJECTED
A status indicating that the message was rejected by the moderator

See Also:
Constant Field Values
Method Detail

getDestination

public java.lang.String getDestination()
returns the conference's address.


addMessage

public void addMessage(Message message)
                throws CollaborationException
add a message, which will be received by other parties in the conference.

Parameters:
message - message
Throws:
CollaborationException

addModeratedMessage

public void addModeratedMessage(Message message,
                                int status,
                                java.lang.String reason)
                         throws CollaborationException
This method should be used submit and approve moderated messages. The users who have a LISTEN access to the room and wish to publish a message to the room should use set the status as STATUS_SUBMIT. Moderators should use this method to send a status to the requestor.The room should already be moderated by some moderator otherwise a CollaborationException will be thrown.

Parameters:
message - Message to be submitted for moderation by users with a LISTEN access or The modified message after approval by the moderator. If there was no modification to the message then it should be same as the original message received.
status - - The status of the message as defined in Conference.
reason - - The comments on the moderated message.While submitting the message the reason may be ignored.
Throws:
CollaborationException

leave

public void leave()
leave the conference. This makes this Conference object unusable.


join

public void join(ConferenceListener listener)
          throws CollaborationException
invoked by the application to specify that the user accepts the conference and to pass the conference listener. It may only be called once, only by an invitee and before any other method in this class. It has no effect otherwise. It will use the current user id as the default nick name.

Parameters:
listener - conference handler
Throws:
CollaborationException

join

public void join(java.lang.String nick,
                 ConferenceHistory history,
                 ConferenceListener listener)
          throws CollaborationException
invoked by the application to specify that the user accepts the conference and to pass the conference listener and a nick name. It can be called multiple times with different nick names.

Parameters:
nick - The nick name to be used in the conference
history - The detail about the history messages. It should be null if the default behaviour is desired.
listener - conference handler
Throws:
CollaborationException

createMessage

public Message createMessage()
                      throws CollaborationException
create a new message

Returns:
a brand new, empty Message.
Throws:
CollaborationException

createInviteMessage

public InviteMessage createInviteMessage()
                                  throws CollaborationException
create an invite message

Returns:
the invite message
Throws:
CollaborationException

invite

public void invite(int accessLevel,
                   Message message,
                   InviteMessageStatusListener listener)
            throws CollaborationException
invite another user to this conference. May only be called by members with INVITE privileges.

Parameters:
accessLevel - privilege to assign to the invitee, if different from the conference's default. It may not exceed the caller's access level.
message - invite message. The list of invitees is provided as the list of receipients for the invite message
listener - status listener for the invite
Throws:
CollaborationException

listPrivileges

public java.util.Map listPrivileges()
                             throws CollaborationException
get the privileges of the all the users affiliated with the bulletin board

Returns:
map of users and the access levels that they have to the conference Value of each element returned in the map is an Integer object.
Throws:
CollaborationException

setPrivileges

public void setPrivileges(java.util.Map map)
                   throws CollaborationException
sets the privleges of the users to the conference on the server

Parameters:
map - Map of users affiliated to the conference and their accesslevels. Value of each element in the map has to be an Integer object.
Throws:
CollaborationException

getPrivilege

public int getPrivilege()
                 throws CollaborationException
return the current user's access level

Throws:
CollaborationException
See Also:
Conference

getPrivilege

public int getPrivilege(java.lang.String uid)
                 throws CollaborationException
Parameters:
uid - fully-qualified principal identifier return the specified principal's access level
Throws:
CollaborationException

setPrivilege

public void setPrivilege(java.lang.String uid,
                         int accessLevel)
                  throws CollaborationException
set a principal's privilege for this conference. Can only be called by member with MANAGE

Parameters:
accessLevel - access level to set for this principal
uid - fully-qualified principal identifier
Throws:
CollaborationException

hasPrivilege

public boolean hasPrivilege(int accessLevel)
                     throws CollaborationException
checks if the user has the required privilege for this conference.

Parameters:
accessLevel - access level to set for this principal
Returns:
boolean returns true if the user has the required privilege.
Throws:
CollaborationException

setDefaultPrivilege

public void setDefaultPrivilege(int accessLevel)
                         throws CollaborationException
set the default access level for members, unless specified otherwise. Can only be called by member with MANAGE

Parameters:
accessLevel - access level
Throws:
CollaborationException

getDefaultPrivilege

public int getDefaultPrivilege()
                        throws CollaborationException
return the conference's default access level

Throws:
CollaborationException

close

public void close()
           throws CollaborationException
terminates the conference This will have the effect of destroying all currently archived messages (for a bulletin board) and unsubscribing all current subscribe members. It can only be called with MANAGE privilege.

Throws:
CollaborationException

getProperty

public java.lang.String getProperty(java.lang.String attribute)
get a conference property

Parameters:
attribute - property name
Returns:
property value

setProperty

public void setProperty(java.lang.String attribute,
                        java.lang.String value)
                 throws CollaborationException
set a conference property

Parameters:
attribute - property name
value - property value
Throws:
CollaborationException

moderate

public void moderate(boolean start)
              throws CollaborationException
Start or stop the moderation

Parameters:
start - true if moderations is to be started
Throws:
CollaborationException

isPublic

public boolean isPublic()
Tells whether this conference is public or persistent.


getParticipants

public java.util.Collection getParticipants()
                                     throws CollaborationException
Lists the participants in the room.

Returns:
Collection a list of uids of the participants.
Throws:
CollaborationException

getDisplayName

public java.lang.String getDisplayName()
returns the conference display name

Returns:
conference display name if available, null otherwise

setDisplayName

public void setDisplayName(java.lang.String name)
                    throws ServiceUnavailableException
sets the display name. Only local storage is modified. save must be called in order to commit the change of name to the server.

Parameters:
name - new display name
Throws:
ServiceUnavailableException

save

public void save()
          throws CollaborationException
commit the current configuration to the server's persistent store.

Throws:
CollaborationException

setEventMask

public void setEventMask(int mask)
                  throws ServiceUnavailableException
Sets access levels for which conference events are generated. The purpose of setting a presence broadcast mask is to support large conferences in which membership events for most participants do not need to be communicated. Only local storage is modified. save must be called in order to commit the change of name to the server.

Parameters:
mask - bitmask of access values which defining for which participants conference events are to be generated and received. The service does not generate membership updates for participants whose access does not match this mask.
Throws:
ServiceUnavailableException

getEventMask

public int getEventMask()
                 throws ServiceUnavailableException
get access levels for which conference events are generated.

Returns:
bitmask of access values which defining for which participants conference events are to be generated and received. The service does not generate membership updates for participants whose access does not match this mask.
Throws:
ServiceUnavailableException