de.tubs.macs.control.floor
Class FloorControl

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--de.tubs.macs.control.floor.FloorControl

public class FloorControl

extends java.lang.Thread

This class provides methods for a Session Controller to access and control the floor and floor control policy for each resource in one session. Thus, each session should have an own object of this class.

Author:

Martin Willers

Field Summary

protected Debug	debug
(package private) static int	FLOOR_GRANTED
(package private) static int	FLOOR_LOOSE
(package private) static int	FLOOR_LOOSE_RETURN
(package private) static int	FLOOR_REDRAWN
(package private) static int	FLOOR_RELEASE
(package private) static int	FLOOR_REQUESTED
(package private) static int	FLOORCHAIR_SET
(package private) static int	GROUP_ADD
(package private) static int	GROUP_REMOVE
static int	PC_CHAIRGUIDED
static int	PC_PREVIEW
static int	PC_REQUESTS
static int	PC_TIMEOUT
static int	PC_USERGUIDED
static int	PC_USERLIST
(package private) static int	POLICY_SET
(package private) static int	REQUEST_STATUS_ALL
(package private) static int	RESOURCE_ADDED
(package private) static int	RESOURCE_REMOVED
(package private) static int	STATUS_ALL
(package private) static int	TIMESLICE_HARD_SET
(package private) static int	TIMESLICE_SOFT_RESET
(package private) static int	TIMESLICE_SOFT_SET
(package private) static int	USER_ADDED
(package private) static int	USER_REMOVED
(package private) static int	USERLIST_SET

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY, values

Constructor Summary

FloorControl(Session session, MacsSessionController controller)
Construct a new FloorControl-object for the specified session and session controller.

Method Summary

void	addToUserGroup(ObjectID groupid, ObjectID user)
(package private) void	addUser(long res_id) Add the local user to list of users being able to share this resource actively.
(package private) boolean	amFloorChair()
(package private) boolean	amInGroupWith(ObjectID user)
boolean	audioFloorReleased(java.lang.Object channelID) Release the floor for the audio-application handling the specified channel-id.
boolean	audioFloorRequested(java.lang.Object channelID) Request the floor for the audio-application handling the specified channel-id.
boolean	closeAudioChannel(java.lang.Object channelID) Close the specified audio channel.
(package private) boolean	deregisterResource(long res_id) Deregister a resource that has previously been registered.
java.lang.Object[]	enumeratePolicies() Returns an array with all policies that are known to the system.
java.lang.Object[]	enumeratePolicies(long res_id) Returns an array with all policies that are valid for the specified resource.
long[]	enumerateResources() Returns an array with all resource-ids currently known to the system.
void	exit() This method must be called by the session when shutting down.
(package private) FloorResource	findRes(long res_id)
(package private) void	floorRedrawn(long res_id)
(package private) void	floorRelease(long res_id, ObjectID releaser)
(package private) void	floorRequested(long res_id, ObjectID requester)
java.util.Vector	getCurrentHolder(long res_id) Returns the users who are the current Floor Holder for the specified resource.
java.util.Vector	getDeterminedUserlist(long res_id) Returns the list of users who are allowed (by the floor chair) to set the floor holder.
ObjectID	getFloorChair() Returns the current floor chair.
(package private) Group	getGroupOf(ObjectID user)
long	getHardTimeslice(long res_id) Returns the hard timeslice for the specified resource.
java.util.Vector	getNextHolder(long res_id) Returns the user that is likely to be the next Floor Holder for the specified resource.
int	getPolicyCapabilities(long res_id) Returns a bitvector containing the capabilities of a policy for the specified resource.
java.lang.String	getPolicyDescription(long res_id) Returns a short textual description of the current Floor Control Policy for the specified resource.
java.lang.String	getPolicyName(long res_id) Returns the name of the current Floor Control Policy for the specified resource.
java.lang.String	getPolicyName(java.lang.Object id) Returns the name of the policy specified by its id.
long	getRemainingHardTime(long res_id) Returns the remaining hard time for the current Floor Holder to keep the floor for the specified resource. This differs from the #getRemainingSoftTime()-method in that this is the maximum time, which cannot be extended by the user (only by the floor chair).
long	getRemainingSoftTime(long res_id) Returns the remaining time for the current Floor Holder to keep the floor for the specified resource. This differs from the #getRemainingHardTime()-methode in that this timeout can be extended by the application by calling the resetTimeout()-method of its Floor-object for this resource.
java.lang.String	getResourceName(long res_id) Returns the name of the resource specified by its resource-id, or null if the resource doesn't exist.
long	getSoftTimeslice(long res_id) Returns the timeslice for the specified resource.
(package private) User	getuser(ObjectID id)
java.util.Vector	getUserRequests(long res_id) Returns a list of users that have requested the floor for the specified resource.
(package private) void	groupAdd(ObjectID userid, ObjectID groupid)
(package private) void	groupRemove(ObjectID userid, ObjectID groupid)
boolean	isCurrentHolder(long res_id, ObjectID user) Returns if the specified user is the (or just one) current Floor Holder for the specified resource.
(package private) boolean	isInGroupWith(ObjectID user1, ObjectID user2)
(package private) boolean	isLocaluser(ObjectID userid)
boolean	maySetHolder(long res_id, ObjectID user) Returns if the specified user is allowed to set a new floor holder for the specified resource.
(package private) java.lang.Object	notifyApplication(MacsApplication app, int msgid, long resid, java.lang.Object data)
(package private) void	notifyController(int msgid, long res_id, java.lang.Object data)
java.lang.Object	openAudioChannel(java.util.Vector users, boolean useFloorcontrol) Open a new audio channel with the specified users participating.
java.lang.Object	openGenericAudioChannel(boolean useFloorcontrol) Open the "generic" audio channel.
void	processSessionEvent(SessionEvent e) Received a SessionEvent.
void	receive(java.lang.Object object) This method gets called by Session.receiveData(), as soon as a received message in SessionNet.receiveObject() is recognized as a Floor-message.
(package private) long	registerResource(java.lang.String name, MacsApplication app, boolean isAudio, int policyFilter)
(package private) void	release(long res_id) Notification by a local application that it doesn't need the floor for the specified resource anymore.
void	removeFromUserGroup(ObjectID groupid, ObjectID user)
(package private) void	removeUser(long res_id) Remove the local user from list of users being able to share this resource actively.
(package private) int	request(long res_id) Handle a floor-request by a local application for the specified resource.
boolean	requestFloorChair(ObjectID userid) Request that the specified user becomes the floor chair.
boolean	requestHolder(long res_id, ObjectID userid) Request that the specified user obtains the floor for the specified resource.
boolean	requestHoldersInOrder(long res_id, java.util.Vector users) Set a list of users who are to obtain the floor, one after another.
boolean	requestPolicy(long res_id, java.lang.Object id) Request a new Floor Control Policy for the specified resource.
boolean	requestResourceGroupFloor(ObjectID userid) Request that the specified user obtains the floor for all resources that have been specified in MACS.properties as belonging to a resource group for the current session type.
(package private) java.util.Vector	requestStatusAll()
(package private) void	resetSoftTimeout(long res_id) Reset the timeout for this resource to indicate that it's still being used.
(package private) void	resourceAdded(long res_id, java.util.Vector data)
(package private) void	resourceRemoved(long res_id)
void	run() Standard method called to execute this thread.
(package private) void	sendGranted(long res_id, ObjectID userid, java.lang.Object data)
(package private) void	sendLoose(long res_id, ObjectID nextHolder)
(package private) void	sendRedrawn(long res_id)
(package private) void	sendRelease(long res_id, ObjectID userid)
(package private) void	sendRequested(long res_id, ObjectID userid)
(package private) void	sendRequestStatusAll()
(package private) void	sendUserlist(long res_id, java.lang.Object data)
boolean	setDeterminedUserlist(long res_id, java.util.Vector ulist) Set a list of users who are allowed to set the floor holder.
(package private) void	setFloorChair(ObjectID newChair)
boolean	setHardTimeslice(long res_id, long duration) Set the length of a hard timeslice for specified resource to the specified amount of milliseconds.
boolean	setSoftTimeslice(long res_id, long duration) Set the length of a soft time slice for the specified resource to the specified amount of milliseconds.
(package private) void	statusAll(java.util.Vector rlist)
(package private) void	timeHardSet(long res_id, long duration)
(package private) void	timeSoftReset(long res_id, long last_time)
(package private) void	timeSoftSet(long res_id, long duration)
(package private) void	userAdded(long res_id, ObjectID userid)
(package private) void	userlistSet(long res_id, java.util.Vector data)
(package private) void	userRemoved(long res_id, ObjectID userid)

Methods inherited from class java.lang.Thread

, activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

debug

protected Debug debug

PC_TIMEOUT

public static int PC_TIMEOUT

PC_USERLIST

public static int PC_USERLIST

PC_CHAIRGUIDED

public static int PC_CHAIRGUIDED

PC_USERGUIDED

public static int PC_USERGUIDED

PC_REQUESTS

public static int PC_REQUESTS

PC_PREVIEW

public static int PC_PREVIEW

RESOURCE_ADDED

static final int RESOURCE_ADDED

RESOURCE_REMOVED

static final int RESOURCE_REMOVED

USER_ADDED

static final int USER_ADDED

USER_REMOVED

static final int USER_REMOVED

FLOOR_REQUESTED

static final int FLOOR_REQUESTED

FLOOR_RELEASE

static final int FLOOR_RELEASE

REQUEST_STATUS_ALL

static final int REQUEST_STATUS_ALL

STATUS_ALL

static final int STATUS_ALL

POLICY_SET

static final int POLICY_SET

FLOORCHAIR_SET

static final int FLOORCHAIR_SET

FLOOR_GRANTED

static final int FLOOR_GRANTED

FLOOR_LOOSE

static final int FLOOR_LOOSE

FLOOR_LOOSE_RETURN

static final int FLOOR_LOOSE_RETURN

FLOOR_REDRAWN

static final int FLOOR_REDRAWN

GROUP_ADD

static final int GROUP_ADD

GROUP_REMOVE

static final int GROUP_REMOVE

TIMESLICE_SOFT_SET

static final int TIMESLICE_SOFT_SET

TIMESLICE_HARD_SET

static final int TIMESLICE_HARD_SET

TIMESLICE_SOFT_RESET

static final int TIMESLICE_SOFT_RESET

USERLIST_SET

static final int USERLIST_SET

Constructor Detail

FloorControl

public FloorControl(Session session,
                    MacsSessionController controller)

Construct a new FloorControl-object for the specified session and session controller.

Method Detail

run

public void run()

Standard method called to execute this thread.

Overrides:

run in class java.lang.Thread

exit

public void exit()

This method must be called by the session when shutting down.

processSessionEvent

public void processSessionEvent(SessionEvent e)

Received a SessionEvent.

Parameters:

e - a SessionEvent.

registerResource

long registerResource(java.lang.String name,
                      MacsApplication app,
                      boolean isAudio,
                      int policyFilter)

deregisterResource

boolean deregisterResource(long res_id)

Deregister a resource that has previously been registered. This method is called by exit()-method of class Floor.

Parameters:

res_id - a long-value specifying a resource-id.

Returns:

true if a resource with this id had been registered, false otherwise.

addUser

void addUser(long res_id)

Add the local user to list of users being able to share this resource actively. This method is called by setActive()-method of class Floor.

Parameters:

res_id - a long-value, specifying a resource-id.

removeUser

void removeUser(long res_id)

Remove the local user from list of users being able to share this resource actively. This method is called by setInactive()-method of class Floor.

Parameters:

res_id - a resource-id.

resetSoftTimeout

void resetSoftTimeout(long res_id)

Reset the timeout for this resource to indicate that it's still being used. This method is called by resetTimeout()-methode of class Floor.

request

int request(long res_id)

Handle a floor-request by a local application for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

0 if floor is already owned by caller, -1 if request is rejected (eg. policy doesn't allow requesting), >0 if request is acklowledged. (number in request-queue returned??)

release

void release(long res_id)

Notification by a local application that it doesn't need the floor for the specified resource anymore.

Parameters:

res_id - a resource-id.

amFloorChair

boolean amFloorChair()

isLocaluser

boolean isLocaluser(ObjectID userid)

enumerateResources

public long[] enumerateResources()

Returns an array with all resource-ids currently known to the system.

getResourceName

public java.lang.String getResourceName(long res_id)

Returns the name of the resource specified by its resource-id, or null if the resource doesn't exist.

Parameters:

res_id - a resource-id.

Returns:

a String containing the name of the resource.

enumeratePolicies

public java.lang.Object[] enumeratePolicies()

Returns an array with all policies that are known to the system.

Returns:

an array with unique policy-identifiers.

enumeratePolicies

public java.lang.Object[] enumeratePolicies(long res_id)

Returns an array with all policies that are valid for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

an array with unique policy-identifiers.

getPolicyName

public java.lang.String getPolicyName(java.lang.Object id)

Returns the name of the policy specified by its id.

Parameters:

id - a policy-identifier obtained by #enumeratePolicies()

Returns:

the name of the policy, as String.

findRes

FloorResource findRes(long res_id)

getPolicyCapabilities

public int getPolicyCapabilities(long res_id)

Returns a bitvector containing the capabilities of a policy for the specified resource.

PC_TIMEOUT

Timeout values (soft and hard) can be specified to let the floor be redrawn after some time.

PC_USERLIST

A list of users that are to obtain the floor can be specified.

PC_CHAIRGUIDED

The Floor Holder can be set explicitely by special users.

PC_USERGUIDED

The new Floor Holder can be set by special users.

PC_REQUESTS

Requests for obtaining the Floor are permitted.

PC_PREVIEW

The policy allows for insight on remaining time and future floor holders.

Parameters:

res_id - a resource-id.

Returns:

an int-value containing a bit-vector with the constants explained above.

maySetHolder

public boolean maySetHolder(long res_id,
                            ObjectID user)

Returns if the specified user is allowed to set a new floor holder for the specified resource.

Parameters:

res_id - a resource-id.

user - a user-id.

Returns:

true if the current policy on the specified resource allows the specified user to set a new floor holder.

isCurrentHolder

public boolean isCurrentHolder(long res_id,
                               ObjectID user)

Returns if the specified user is the (or just one) current Floor Holder for the specified resource.

Parameters:

res_id - a resource-id.

user - a user.

Returns:

true if the user is a Floor Holder, false otherwise.

getCurrentHolder

public java.util.Vector getCurrentHolder(long res_id)

Returns the users who are the current Floor Holder for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

the users who are the current Floor Holders for the specified resource, or null if resource doesn't exist.

getNextHolder

public java.util.Vector getNextHolder(long res_id)

Returns the user that is likely to be the next Floor Holder for the specified resource. Returns null if the resource doesn't exist or the current Floor Policy doesn't allow for such insight.

Parameters:

res_id - a resource-id.

Returns:

the user that probably is the next Floor Holder, or null.

getPolicyName

public java.lang.String getPolicyName(long res_id)

Returns the name of the current Floor Control Policy for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

a String containing the name, or null if the resource doesn't exist.

getPolicyDescription

public java.lang.String getPolicyDescription(long res_id)

Returns a short textual description of the current Floor Control Policy for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

a String containing the description, or null if the resource doesn't exist.

getUserRequests

public java.util.Vector getUserRequests(long res_id)

Returns a list of users that have requested the floor for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

a Vector containing ObjectIDs of all users that have requested the floor.

getDeterminedUserlist

public java.util.Vector getDeterminedUserlist(long res_id)

Returns the list of users who are allowed (by the floor chair) to set the floor holder.

Parameters:

res_id - a resource-id.

Returns:

a Vector containing the user-ids (of class ObjectID).

setDeterminedUserlist

public boolean setDeterminedUserlist(long res_id,
                                     java.util.Vector ulist)

Set a list of users who are allowed to set the floor holder. Only the floor chair is allowed to do that, naturally.

Parameters:

res_id - a resource-id.

ulist - a Vector containing the user-ids (of class ObjectID).

Returns:

false if the user is not allowed to provide a userlist (or the resource doesn't exist), true otherwise.

requestPolicy

public boolean requestPolicy(long res_id,
                             java.lang.Object id)

Request a new Floor Control Policy for the specified resource.

Parameters:

res_id - a resource-id.

id - an Object, specifying a policy.

Returns:

true if the request is granted, false if the request is rejected.

requestFloorChair

public boolean requestFloorChair(ObjectID userid)

Request that the specified user becomes the floor chair.

Parameters:

userid - a user-id.

Returns:

true if the request is granted, false otherwise.

getFloorChair

public ObjectID getFloorChair()

Returns the current floor chair.

Returns:

the userid of the current floor chair.

requestHolder

public boolean requestHolder(long res_id,
                             ObjectID userid)

Request that the specified user obtains the floor for the specified resource.

Parameters:

res_id - a resource-id.

userid - the user that is to obtain the floor.

Returns:

true if the request is granted, false if the request is rejected.

requestHoldersInOrder

public boolean requestHoldersInOrder(long res_id,
                                     java.util.Vector users)

Set a list of users who are to obtain the floor, one after another.

Parameters:

res_id - a resource-id.

users - the users that are to obtain the floor.

Returns:

true if the request is granted, false if the request is rejected.

requestResourceGroupFloor

public boolean requestResourceGroupFloor(ObjectID userid)

Request that the specified user obtains the floor for all resources that have been specified in MACS.properties as belonging to a resource group for the current session type.

Parameters:

userid - the user that is to obtain the floors.

Returns:

true if the request is granted, false if the request is rejected.

getRemainingSoftTime

public long getRemainingSoftTime(long res_id)

Returns the remaining time for the current Floor Holder to keep the floor for the specified resource.
This differs from the #getRemainingHardTime()-methode in that this timeout can be extended by the application by calling the resetTimeout()-method of its Floor-object for this resource.

Parameters:

res_id - a resource-id.

Returns:

a long-value, specifying the remaining time in milliseconds, or -1 if there is no timeout.

getRemainingHardTime

public long getRemainingHardTime(long res_id)

Returns the remaining hard time for the current Floor Holder to keep the floor for the specified resource.
This differs from the #getRemainingSoftTime()-method in that this is the maximum time, which cannot be extended by the user (only by the floor chair).

Parameters:

res_id - a resource-id.

Returns:

a long-value, specifying the remaining time in millisecons, or -1 if there is no hard timeout.

setSoftTimeslice

public boolean setSoftTimeslice(long res_id,
                                long duration)

Set the length of a soft time slice for the specified resource to the specified amount of milliseconds.

Parameters:

res_id - a resource-id.

duration - the amount in milliseconds, or 0 (meaning "forever").

Returns:

false if the user is not allowed to set the time slice (or the resource doesn't exist), true otherwise.

setHardTimeslice

public boolean setHardTimeslice(long res_id,
                                long duration)

Set the length of a hard timeslice for specified resource to the specified amount of milliseconds.

Parameters:

res_id - a resource-id.

duration - the amount in milliseconds, or 0 (meaning "forever").

Returns:

false if the user is not allowed to set the time slice (or the resource doesn't exist), true otherwise.

getSoftTimeslice

public long getSoftTimeslice(long res_id)

Returns the timeslice for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

the timeslice in milliseconds.

getHardTimeslice

public long getHardTimeslice(long res_id)

Returns the hard timeslice for the specified resource.

Parameters:

res_id - a resource-id.

Returns:

the timeslice in milliseconds.

addToUserGroup

public void addToUserGroup(ObjectID groupid,
                           ObjectID user)

removeFromUserGroup

public void removeFromUserGroup(ObjectID groupid,
                                ObjectID user)

getGroupOf

Group getGroupOf(ObjectID user)

amInGroupWith

boolean amInGroupWith(ObjectID user)

isInGroupWith

boolean isInGroupWith(ObjectID user1,
                      ObjectID user2)

openAudioChannel

public java.lang.Object openAudioChannel(java.util.Vector users,
                                         boolean useFloorcontrol)

Open a new audio channel with the specified users participating.

closeAudioChannel

public boolean closeAudioChannel(java.lang.Object channelID)

Close the specified audio channel.

openGenericAudioChannel

public java.lang.Object openGenericAudioChannel(boolean useFloorcontrol)

Open the "generic" audio channel.

audioFloorRequested

public boolean audioFloorRequested(java.lang.Object channelID)

Request the floor for the audio-application handling the specified channel-id.

audioFloorReleased

public boolean audioFloorReleased(java.lang.Object channelID)

Release the floor for the audio-application handling the specified channel-id.

notifyController

void notifyController(int msgid,
                      long res_id,
                      java.lang.Object data)

notifyApplication

java.lang.Object notifyApplication(MacsApplication app,
                                   int msgid,
                                   long resid,
                                   java.lang.Object data)

setFloorChair

void setFloorChair(ObjectID newChair)

resourceAdded

void resourceAdded(long res_id,
                   java.util.Vector data)

resourceRemoved

void resourceRemoved(long res_id)

userAdded

void userAdded(long res_id,
               ObjectID userid)

userRemoved

void userRemoved(long res_id,
                 ObjectID userid)

floorRequested

void floorRequested(long res_id,
                    ObjectID requester)

floorRelease

void floorRelease(long res_id,
                  ObjectID releaser)

floorRedrawn

void floorRedrawn(long res_id)

groupAdd

void groupAdd(ObjectID userid,
              ObjectID groupid)

groupRemove

void groupRemove(ObjectID userid,
                 ObjectID groupid)

timeSoftSet

void timeSoftSet(long res_id,
                 long duration)

timeHardSet

void timeHardSet(long res_id,
                 long duration)

timeSoftReset

void timeSoftReset(long res_id,
                   long last_time)

userlistSet

void userlistSet(long res_id,
                 java.util.Vector data)

requestStatusAll

java.util.Vector requestStatusAll()

statusAll

void statusAll(java.util.Vector rlist)

sendRequestStatusAll

void sendRequestStatusAll()

sendGranted

void sendGranted(long res_id,
                 ObjectID userid,
                 java.lang.Object data)

sendLoose

void sendLoose(long res_id,
               ObjectID nextHolder)

sendRedrawn

void sendRedrawn(long res_id)

sendRequested

void sendRequested(long res_id,
                   ObjectID userid)

sendRelease

void sendRelease(long res_id,
                 ObjectID userid)

sendUserlist

void sendUserlist(long res_id,
                  java.lang.Object data)

receive

public void receive(java.lang.Object object)

This method gets called by Session.receiveData(), as soon as a received message in SessionNet.receiveObject() is recognized as a Floor-message.

Parameters:

object - the message-object.

getuser

User getuser(ObjectID id)