org.frogx.service.api
Interface MUGMatch


public interface MUGMatch

A MUGMatch provides the game logic, handles the state of the game and provides roles which can be assigned by an MUGOccupant to become a player.

Author:
Günther Nieß

Nested Class Summary
static class MUGMatch.Status
          The Status of a MUGMatch is part of the game state within a MUGRoom and describes if the game is running, paused or can be configured.
 
Method Summary
 void addSpectator(MUGOccupant occupant)
          If a user joins the room as a spectator or a player releases the game role this function is called.
 void destroy()
          This method is called when the match will be destroyed.
 java.util.Collection<org.dom4j.Element> getConfigurationForm()
          Get a collection of xml elements which were delivered to the owner if he wants to configure the match
 java.util.Collection<java.lang.String> getFreeRoles()
          Get a collection of the available free roles in the match.
 java.util.Collection<MUGOccupant> getPlayers()
          Get a collection of the players in the match.
 java.lang.String getRole(MUGOccupant player)
          Get the role of an MUGOccupant.
 org.dom4j.Element getState()
          Get xml element which represents the actual match state.
 MUGMatch.Status getStatus()
          Get the current status of the match.
 void leave(MUGOccupant occupant)
          An MUGOccupant leaves the match.
 void processTurn(MUGOccupant player, java.util.Collection<org.dom4j.Element> moves)
          A player (an occupant reserved a game role) want to make a turn.
 void releaseRole(MUGOccupant player)
          A MUGOccupant want to release his role.
 java.lang.String reserveFreeRole(MUGOccupant occupant)
          An occupant which have no role yet can reserve any free game role.
 void reserveRole(MUGOccupant occupant, java.lang.String roleName)
          An occupant which have no role yet can try to reserve a game role.
 void setConfiguration(java.util.Collection<org.dom4j.Element> config)
          Configure the match with help of the ConfigurationFrom get by getConfigurationForm().
 void setConstructedState(org.dom4j.Element state)
          In some games the owner can request a constructed match by sending an starting match state.
 void start()
          The room occupants want to start the game.
 

Method Detail

addSpectator

void addSpectator(MUGOccupant occupant)
If a user joins the room as a spectator or a player releases the game role this function is called.

Parameters:
occupant - The room occupant who wants to watch the game.

reserveFreeRole

java.lang.String reserveFreeRole(MUGOccupant occupant)
An occupant which have no role yet can reserve any free game role.

Parameters:
occupant - The room occupant who wants to reserve a role.
Returns:
The name of the reserved role or null if no role could be reserved.

reserveRole

void reserveRole(MUGOccupant occupant,
                 java.lang.String roleName)
                 throws ConflictException,
                        GameConfigurationException
An occupant which have no role yet can try to reserve a game role. If the role isn't available this method returns null.

Parameters:
occupant - The room occupant who wants to reserve a role.
roleName - The name of the role which wants the occupant reserve.
Throws:
ConflictException - If the role is reserved by another occupant.
GameConfigurationException - If the role doesn't exist.

getPlayers

java.util.Collection<MUGOccupant> getPlayers()
Get a collection of the players in the match.

Returns:
A collection of the players in the match.

getRole

java.lang.String getRole(MUGOccupant player)
Get the role of an MUGOccupant.

Parameters:
player - The owner of the role.
Returns:
The name of the role which is reserved by the player.

getFreeRoles

java.util.Collection<java.lang.String> getFreeRoles()
Get a collection of the available free roles in the match.

Returns:
A collection of free roles.

getState

org.dom4j.Element getState()
Get xml element which represents the actual match state. This state is used for the presence and delivered to the room occupants.

Returns:
A xml element with the match state.

start

void start()
           throws RequiredPlayerException,
                  GameConfigurationException
The room occupants want to start the game. If the match is not yet ready to start because some required roles are not assigned a RequiredPlayerException is released. If no playable configuration is available the GameConfigurationException triggered.

Throws:
RequiredPlayerException - This Exception is thrown if a required role isn't assigned by a occupant.
GameConfigurationException - This Exception is thrown if no playable configuration is available.

processTurn

void processTurn(MUGOccupant player,
                 java.util.Collection<org.dom4j.Element> moves)
                 throws RequiredPlayerException,
                        GameConfigurationException,
                        InvalidTurnException,
                        org.xmpp.component.ComponentException
A player (an occupant reserved a game role) want to make a turn.

Parameters:
player - The MUGOccupant which wants to make the turn.
moves - A collection of the xml elements for the turn.
Throws:
RequiredPlayerException - This Exception is thrown if a required role isn't assigned by a occupant.
GameConfigurationException - This Exception is thrown if the match hasn't started yet.
InvalidTurnException - If the turn is invalid.
org.xmpp.component.ComponentException

releaseRole

void releaseRole(MUGOccupant player)
A MUGOccupant want to release his role.

Parameters:
player - The MUGOccupant which wants to release his role.

getConfigurationForm

java.util.Collection<org.dom4j.Element> getConfigurationForm()
Get a collection of xml elements which were delivered to the owner if he wants to configure the match

Returns:
xml elements which describes what the owner can configure

setConfiguration

void setConfiguration(java.util.Collection<org.dom4j.Element> config)
Configure the match with help of the ConfigurationFrom get by getConfigurationForm(). If the Collection of configure elements is null the default configuration is applied.

Parameters:
config - A collection of xml elements which describes the new configuration or null if the default configuration is applied.

setConstructedState

void setConstructedState(org.dom4j.Element state)
In some games the owner can request a constructed match by sending an starting match state. If the game didn't support that just throw an IllegalArgumentException or an UnsupportedGameException if it is not implemented yet.

Parameters:
state - The starting match state.

getStatus

MUGMatch.Status getStatus()
Get the current status of the match.

Returns:
The pressent match status.

leave

void leave(MUGOccupant occupant)
An MUGOccupant leaves the match. This means an occupant is neither a player nor a spectator anymore.

Parameters:
occupant - The occupant who leaves the match.

destroy

void destroy()
This method is called when the match will be destroyed.



Copyright © 2009. All Rights Reserved.