org.frogx.service.api
Interface MUGRoom

All Superinterfaces:
org.xmpp.resultsetmanagement.Result

public interface MUGRoom
extends org.xmpp.resultsetmanagement.Result

A game room on the Multi-User Gaming server manages its occupants, sends game moves, invitations, presence information,...

Author:
Günther Nieß

Method Summary
 void addMember(org.xmpp.packet.JID newMember, MUGOccupant occupant)
          An occupant wants to add a new member.
 void broadcastPresence(MUGOccupant occupant)
          Broadcast the presence of an occupant to all other occupants (expecting him).
 void broadcastRoomPresence()
          Broadcast the room and match information to all occupants.
 void broadcastTurn(java.util.Collection<org.dom4j.Element> moves, MUGOccupant player)
          A MUGMatch may want to broadcast a game moves.
 boolean canDiscoverOccupants()
          Return true if it's allowed that the list of occupants is publicly available.
 boolean canOccupantsInvite()
          Returns true if it's allowed that the occupants can invite other users.
 MUGOccupant changeNickname(java.lang.String oldNick, java.lang.String newNick, org.xmpp.packet.Presence newPresence)
          An MUGOccupant want to change his nickname.
 void destroy()
          Destroy the room.
 java.lang.String getDescription()
          Get a description of the game room.
 java.util.Collection<org.xmpp.forms.FormField> getExtraExtendedDiscoFields()
          Get additional extended service discovery fields for more informations about this room.
 java.util.Collection<java.lang.String> getExtraFeatures()
          Obtains a collection of additional service discovery features.
 MultiUserGame getGame()
          Returns the MultiUserGame which can be played within the room.
 org.xmpp.packet.JID getJID()
          Get the JID of this room e.g. chess@games.example.com.
 MUGMatch getMatch()
          Get the current MUGMatch which handels the game state and logic.
 int getMaxOccupants()
          Get the number of occupants which are able to join the MUGRoom.
 MUGService getMUGService()
          Get the MUGService which is hosting the room.
 java.lang.String getName()
          Get the name of this room.
 java.lang.String getNaturalLanguageName()
          Get a human readable name of this room which was configured by the owner.
 java.util.Collection<MUGOccupant> getOccupants()
          Obtain a collection of all MUGOccupants in the game room.
 int getOccupantsCount()
          Returns the current number of occupants in the MUGRoom.
 org.xmpp.packet.JID getOwner()
          Get the JID of the room owner.
 java.lang.String getPassword()
          Returns the password that the user must provide to enter the room.
 int getPlayersCount()
          Returns the current number of occupants reserved a game role and playing a match.
 void handleOwnerIQ(org.xmpp.packet.IQ packet, MUGOccupant occupant)
          Handle game room requests within the Owner namespace.
 void invite(org.xmpp.packet.JID recipient, java.lang.String reason, MUGOccupant invitor)
          An occupant want to invite another user to join the game room.
 boolean isFullyAnonymous()
          Returns true if it's a room in which an occupant's full JID can't be discovered by anyone.
 boolean isLocked()
          Returns true if the room is locked.
 boolean isMembersOnly()
          Returns true if a user cannot join the room without being on the member list.
 boolean isModerated()
          Returns true if the room owner is allowed to kick users, revoke roles amd save the match.
 boolean isNonAnonymous()
          Returns true if it's a room in which an occupant's full JID is exposed to all other occupants.
 boolean isPasswordProtected()
          Returns true if a user cannot enter without first providing the correct password.
 boolean isPublicRoom()
          Returns true if the room is visible through service discovery or jabber search.
 boolean isSemiAnonymous()
          Returns true if it's a room in which an occupant's full JID can be discovered only by the room owner.
 MUGOccupant join(java.lang.String nick, java.lang.String passwd, org.xmpp.packet.JID fullJID, org.xmpp.packet.Presence presence)
          A user want to join the game room.
 void leave(MUGOccupant occupant)
          An occupant is quitting the participation of this room.
 void sendInvitationRejection(org.xmpp.packet.JID recipient, java.lang.String reason, org.xmpp.packet.JID sender)
          A user declines an invitation.
 void sendPrivatePacket(org.xmpp.packet.Packet packet, MUGOccupant occupant)
          A occupant can send another occupant a private message.
 void sendTurn(java.util.Collection<org.dom4j.Element> moves, MUGOccupant player, MUGOccupant recipient)
          A MUGMatch may want to send game moves.
 boolean startMatch(MUGOccupant occupant)
          An MUGOccupant signals that he is ready to start the match.
 
Methods inherited from interface org.xmpp.resultsetmanagement.Result
getUID
 

Method Detail

getName

java.lang.String getName()
Get the name of this room. For example chess for the room chess@games.example.com.

Returns:
The name for this room.

getMUGService

MUGService getMUGService()
Get the MUGService which is hosting the room.

Returns:
The MUGService instance which the room is attached to.

getJID

org.xmpp.packet.JID getJID()
Get the JID of this room e.g. chess@games.example.com.

Returns:
the JID for this room.

getGame

MultiUserGame getGame()
Returns the MultiUserGame which can be played within the room.

Returns:
The MultiUserGame of this room.

getMatch

MUGMatch getMatch()
Get the current MUGMatch which handels the game state and logic.

Returns:
The current MUGMatch of this room.

getOccupants

java.util.Collection<MUGOccupant> getOccupants()
Obtain a collection of all MUGOccupants in the game room.

Returns:
A collection with all occupants of this room

getNaturalLanguageName

java.lang.String getNaturalLanguageName()
Get a human readable name of this room which was configured by the owner.

Returns:
The human readable name of this room.

getDescription

java.lang.String getDescription()
Get a description of the game room.

Returns:
The description of the game room.

isLocked

boolean isLocked()
Returns true if the room is locked. No user is allowed to join or discover a locked room.

Returns:
True if the room is locked otherwise false.

isPasswordProtected

boolean isPasswordProtected()
Returns true if a user cannot enter without first providing the correct password.

Returns:
True if a user need a password to join the room.

getPassword

java.lang.String getPassword()
Returns the password that the user must provide to enter the room.

Returns:
The password of this room.

isMembersOnly

boolean isMembersOnly()
Returns true if a user cannot join the room without being on the member list. An invitation adds the receiver to the member list.

Returns:
True if the room is a members-only room.

isModerated

boolean isModerated()
Returns true if the room owner is allowed to kick users, revoke roles amd save the match.

Returns:
True if the room is a moderated room.

isPublicRoom

boolean isPublicRoom()
Returns true if the room is visible through service discovery or jabber search.

Returns:
True if the room is listed in a public directory.

isNonAnonymous

boolean isNonAnonymous()
Returns true if it's a room in which an occupant's full JID is exposed to all other occupants.

Returns:
True if the occupants JID is publicly available.

isSemiAnonymous

boolean isSemiAnonymous()
Returns true if it's a room in which an occupant's full JID can be discovered only by the room owner.

Returns:
True if the occupants JID is only available for the room owner.

isFullyAnonymous

boolean isFullyAnonymous()
Returns true if it's a room in which an occupant's full JID can't be discovered by anyone. This respects all occupants privacy.

Returns:
True if the occupants JID can't be discovered by anyone.

canOccupantsInvite

boolean canOccupantsInvite()
Returns true if it's allowed that the occupants can invite other users.

Returns:
True if the occupants are able to invite other users.

canDiscoverOccupants

boolean canDiscoverOccupants()
Return true if it's allowed that the list of occupants is publicly available. This list include all occupants room JID.

Returns:
True if a list of occupant is available trough Service Discovery.

getOwner

org.xmpp.packet.JID getOwner()
Get the JID of the room owner.

Returns:
The JID of the room owner.

getMaxOccupants

int getMaxOccupants()
Get the number of occupants which are able to join the MUGRoom.

Returns:
The maximal number of occupants in this room.

getOccupantsCount

int getOccupantsCount()
Returns the current number of occupants in the MUGRoom.

Returns:
The number of occupants which are in the room.

getPlayersCount

int getPlayersCount()
Returns the current number of occupants reserved a game role and playing a match.

Returns:
The number of players in the room.

getExtraFeatures

java.util.Collection<java.lang.String> getExtraFeatures()
Obtains a collection of additional service discovery features.

Returns:
A collection of additional service discovery features.

getExtraExtendedDiscoFields

java.util.Collection<org.xmpp.forms.FormField> getExtraExtendedDiscoFields()
Get additional extended service discovery fields for more informations about this room.

Returns:
A collection of additional extended service discovery fields.

addMember

void addMember(org.xmpp.packet.JID newMember,
               MUGOccupant occupant)
               throws ForbiddenException
An occupant wants to add a new member.

Parameters:
newMember - The JID of the user which should be added to the member list.
occupant - The occupant who wants to add the new member.
Throws:
ForbiddenException - If the occupant hasn't the permission to add someone to the member list.

broadcastPresence

void broadcastPresence(MUGOccupant occupant)
Broadcast the presence of an occupant to all other occupants (expecting him).

Parameters:
occupant - The occupant whose presence will be broadcasted.

broadcastRoomPresence

void broadcastRoomPresence()
Broadcast the room and match information to all occupants.


broadcastTurn

void broadcastTurn(java.util.Collection<org.dom4j.Element> moves,
                   MUGOccupant player)
                   throws org.xmpp.component.ComponentException
A MUGMatch may want to broadcast a game moves. The turn will also be sent to the acting player.

Parameters:
moves - A collection of XML elements which will be send within a turn.
player - The MUGOccupant which makes the moves.
Throws:
org.xmpp.component.ComponentException - if the turn cannot be sent to all occupants.

changeNickname

MUGOccupant changeNickname(java.lang.String oldNick,
                           java.lang.String newNick,
                           org.xmpp.packet.Presence newPresence)
                           throws NotFoundException,
                                  ConflictException
An MUGOccupant want to change his nickname.

Parameters:
oldNick - The old nickname of the occupant.
newNick - The new nickname of the occupant.
newPresence - The new presence of the occupant.
Returns:
The changed MUGOccupant object.
Throws:
NotFoundException - if the old nickname isn't found in the room.
ConflictException - if the new nickname is already in use.

handleOwnerIQ

void handleOwnerIQ(org.xmpp.packet.IQ packet,
                   MUGOccupant occupant)
                   throws ForbiddenException,
                          java.lang.IllegalArgumentException,
                          GameConfigurationException,
                          UnsupportedGameException
Handle game room requests within the Owner namespace.

Parameters:
packet - The IQ stanza which should be handled.
occupant - The Sender of the IQ request.
Throws:
ForbiddenException - if the sender don't have the permission for his request.
java.lang.IllegalArgumentException - if we don't understand the request.
GameConfigurationException - if the room or match state is not correct.
UnsupportedGameException - if the request is unsupported or not implemented.

invite

void invite(org.xmpp.packet.JID recipient,
            java.lang.String reason,
            MUGOccupant invitor)
            throws ForbiddenException,
                   CannotBeInvitedException
An occupant want to invite another user to join the game room. Note: This doesn't add the recipient to the member list.

Parameters:
recipient - The user which will be invited.
reason - A human readable text for the invitation.
invitor - The MUGOccupant who wants to invite another user.
Throws:
ForbiddenException - if the occupant don't have the permission to invite.
CannotBeInvitedException - if an error occurs during sending the invitation.

join

MUGOccupant join(java.lang.String nick,
                 java.lang.String passwd,
                 org.xmpp.packet.JID fullJID,
                 org.xmpp.packet.Presence presence)
                 throws ServiceUnavailableException,
                        RoomLockedException,
                        UserAlreadyExistsException,
                        UnauthorizedException,
                        ForbiddenException,
                        org.xmpp.component.ComponentException
A user want to join the game room.

Parameters:
nick - The nickname of the user.
passwd - The password for entering the room.
fullJID - The real JID of the user.
presence - The Presence of the user.
Returns:
A MUGOccupant object which represents the new praticipant of the room.
Throws:
ServiceUnavailableException - if the room has reached his capacity.
RoomLockedException - if the room is locked and only the owner is allowed to enter.
UserAlreadyExistsException - if the nickname is already in use.
UnauthorizedException - if the provided password is not correct.
ForbiddenException - if the room is only for members but the user is not on the member list.
org.xmpp.component.ComponentException - if the room is unable to send the presence updates.

sendPrivatePacket

void sendPrivatePacket(org.xmpp.packet.Packet packet,
                       MUGOccupant occupant)
                       throws NotFoundException,
                              org.xmpp.component.ComponentException
A occupant can send another occupant a private message. The recipient is defined by the "to" attribute of the package and must be a room JID.

Parameters:
packet - A XML stanza which should be sent.
occupant - The sender of this packet.
Throws:
NotFoundException - if the recipient (from the to attribute of the package)
org.xmpp.component.ComponentException - if the room is unable to send the packet.

sendInvitationRejection

void sendInvitationRejection(org.xmpp.packet.JID recipient,
                             java.lang.String reason,
                             org.xmpp.packet.JID sender)
                             throws org.xmpp.component.ComponentException
A user declines an invitation.

Parameters:
recipient - The user who was sending the invitation.
reason - A human readable reason for his rejection.
sender - The user who want to decline his invitation.
Throws:
org.xmpp.component.ComponentException - if the room is unable to send the rejection.

sendTurn

void sendTurn(java.util.Collection<org.dom4j.Element> moves,
              MUGOccupant player,
              MUGOccupant recipient)
              throws org.xmpp.component.ComponentException
A MUGMatch may want to send game moves.

Parameters:
moves - A collection of XML elements which will be send within a turn.
player - The MUGOccupant which makes the moves.
recipient - The turn will be send to this MUGOccupant.
Throws:
org.xmpp.component.ComponentException - if the turn cannot be sent.

startMatch

boolean startMatch(MUGOccupant occupant)
                   throws RequiredPlayerException,
                          GameConfigurationException,
                          org.xmpp.component.ComponentException
An MUGOccupant signals that he is ready to start the match. If all player are ready, the room will pass the request on the match.

Parameters:
occupant - The MUGOccupant which is ready for starting.
Returns:
True if the match is started.
Throws:
RequiredPlayerException - if some free roles of the game must be assigned before the match is ready.
GameConfigurationException - if no playable configuration is available.
org.xmpp.component.ComponentException - if the start signal is accepted but could not be reflected to the other occupants.

leave

void leave(MUGOccupant occupant)
An occupant is quitting the participation of this room.

Parameters:
occupant - The leaving occupant.

destroy

void destroy()
Destroy the room. This method should called to cleanup the room.



Copyright © 2009. All Rights Reserved.