multiverse.server.voice
Class BasicVoiceGroup

java.lang.Object
  multiverse.server.voice.BasicVoiceGroup

All Implemented Interfaces:

VoiceGroup

Direct Known Subclasses:

NonpositionalVoiceGroup, PositionalVoiceGroup

public abstract class BasicVoiceGroup
extends java.lang.Object
implements VoiceGroup

This class implements VoiceGroup interface, and is used to implement two important cases of voice groups: presentations and "raid groups".

Field Summary

protected java.util.Set<java.lang.Long>	allowedMembers A set of longs representing the oids of players allowed to join the group.
protected java.lang.Object	association An Object-valued slot, not used by BasicVoiceManager, to allow derived classes to provide an assoiciated object.
int	defaultPriority The default priority of newly-created members of the group.
protected long	groupOid The oid of the group.
protected java.util.concurrent.locks.Lock	lock A lock used by operations on the group
protected static boolean	loggingRecomputeVoices To enable detailed logging of the recompute voices algorithm.
protected int	maxVoices The maximum number of voice channels any single client can have simultaneously transmitting to the client.
protected java.util.Map<java.lang.Long,GroupMember>	members A map from member oid to GroupMember instance for this group.
protected VoiceSender	voiceSender The instance used to send messages to listeners.

Constructor Summary

BasicVoiceGroup(long groupOid, java.lang.Object association, VoiceSender voiceSender, int maxVoices)
Create a BasicVoiceGroup

Method Summary

GroupMember	addMember(long memberOid, VoiceConnection memberCon) Add a member to a group
abstract GroupMember	addMember(long memberOid, VoiceConnection memberCon, int priority, boolean allowedSpeaker) Create a member with the given oid, and associate it with memberCon.
boolean	addMemberAllowed(long memberOid, java.lang.String authToken) Determine if the oid is that of a member of the group.
protected java.lang.String	addString(boolean add) Utility method used in logging.
protected abstract void	changeListening(GroupMember listener, boolean add) Change a listener from not listening to listening, or vice versa
protected abstract void	changeSpeaking(GroupMember speaker, boolean add) Change a speaker from not speaking to speaking, or vice versa
protected boolean	eligibleSpeakerListenerPair(GroupMember speaker, GroupMember listener) A default implementation of a filter that determines if we are allowed to form a voice channel from the given speaker to the given listener.
protected void	endListeningToSpeaker(GroupMember speaker, GroupMember listener, byte voiceNumber) Terminate the voice channel, whose voice channel number is voiceNumber, between the given speaker and listener by sending a deallocate message to the listener's client.
java.util.Set<java.lang.Long>	getAllowedMembers() Return the allowed members
int	getDefaultPriority() Return the default priority of members
long	getGroupOid() Return the group oid of a voice group.
protected GroupMember	getMember(long oid)
boolean	isAllowedSpeaker(long memberOid) Does not need locking, since there are no modifications and the status could change immediately after the call anyway.
boolean	isListener(long memberOid) Does not need locking, since there are no modifications and the status could change immediately after the call anyway.
GroupMember	isMember(long memberOid) Return the member identified by memberOid, or null if there is no such member.
boolean	isMemberSpeaking(long memberOid) Does not need locking, since there are no modifications and the status could change immediately after the call anyway.
abstract boolean	isPositional() Return true if the group is a positional group; that is, if membership in the group is determined by being near the listener, and the priority of speakers is determined by how near any speaker is.
void	onAfterAddMember(long memberOid, long groupOid, boolean allowedSpeaker, byte micVoiceNumber, boolean listenToYourself) A call to this method is made after an addMember() operation.
void	onAfterRemoveMember(long memberOid, long groupOid, boolean allowedSpeaker) A call to this method is made after a removeMember() operation.
protected abstract void	recomputeListenerVoices(GroupMember listener) The set of speakers who should now be heard by this listener (may have) changed; send appropriate voice deallocates and allocates to reflect those changes
protected void	recomputeVoicesFromSpeakerIterator(GroupMember listener, java.util.Iterator<GroupMember> memberIterator, int count) This is central method that recalculates the voices that should be heard by a listener, based on a potential set of voices currently speaking, sending out allocations and deallocations as a result.
boolean	removeMember(long memberOid) Sever all speaker/listener relationships involving the member, and remove the member identified by memberOid.
void	sendVoiceFrameToListeners(long speakerOid, multiverse.server.network.MVByteBuffer buf, byte opcode, int pktSize) Send a voice frame originating with the speaker with the given oid, and contained in the first dataSize bytes of buf, to all eligible listeners
void	setAllowedMembers(java.util.Set<java.lang.Long> allowedMembers) Supply a list of oids of players allowed to be in the group
protected void	setAllowedSpeaker(GroupMember member, boolean add) Change whether a member is allowed to speak or not, and if it was formerly speaking, sever it's speaker to listener relationships by sending voice channel deallocation messages.
void	setAllowedSpeaker(long memberOid, boolean add) Sets whether the member is allowed ot speak.
void	setListener(GroupMember member, boolean add) Change the member supplied to be a listener if add is true, or not a listener if add is false.
void	setListener(long memberOid, boolean add) Change the member with the given oid to be a listener if add is true, or not a listener if add is false.
void	setMemberSpeaking(long memberOid, boolean add) Change a member that is allowed to speak from not speaking to speaking, or vice versa, and do whatever voice deallocation and/or allocation is required as a result.
java.lang.String	toString() Make a string

Methods inherited from class java.lang.Object

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

Field Detail

groupOid

protected long groupOid

The oid of the group.

association

protected java.lang.Object association

An Object-valued slot, not used by BasicVoiceManager, to allow derived classes to provide an assoiciated object.

voiceSender

protected VoiceSender voiceSender

The instance used to send messages to listeners.

maxVoices

protected int maxVoices

The maximum number of voice channels any single client can have simultaneously transmitting to the client.

defaultPriority

public int defaultPriority

The default priority of newly-created members of the group.

allowedMembers

protected java.util.Set<java.lang.Long> allowedMembers

A set of longs representing the oids of players allowed to join the group. If null, then anyone can join the group, or method addMemberAllowed() got overridden.

members

protected java.util.Map<java.lang.Long,GroupMember> members

A map from member oid to GroupMember instance for this group.

loggingRecomputeVoices

protected static boolean loggingRecomputeVoices

To enable detailed logging of the recompute voices algorithm.

lock

protected transient java.util.concurrent.locks.Lock lock

A lock used by operations on the group

Constructor Detail

BasicVoiceGroup

public BasicVoiceGroup(long groupOid,
                       java.lang.Object association,
                       VoiceSender voiceSender,
                       int maxVoices)

Create a BasicVoiceGroup

Parameters:

groupOid - The oid of the group, which is unique across all voice groups.

association - An object-valued data member that is unused in BasicVoiceGroup, but available to derived classes.

voiceSender - The abstraction that allows the voice group to send messages to listeners.

maxVoices - The maximum number of voice channels that may ever be simultaneously in use by any client

Method Detail

getGroupOid

public long getGroupOid()

Return the group oid of a voice group.

Specified by:

getGroupOid in interface VoiceGroup

Returns:

The groupOid of the voice group.

addMemberAllowed

public boolean addMemberAllowed(long memberOid,
                                java.lang.String authToken)

Determine if the oid is that of a member of the group.

Specified by:

addMemberAllowed in interface VoiceGroup

Parameters:

memberOid - The oid of possible group member.

authToken - A string giving the voice client's authentication credentials.

Returns:

True if the memberOid is a member of the group or is allowed to be a member of the group, and false otherwise.

addMember

public GroupMember addMember(long memberOid,
                             VoiceConnection memberCon)

Add a member to a group

Specified by:

addMember in interface VoiceGroup

Parameters:

memberOid - The oid of the newly-created member

memberCon - The VoiceConnection object that embodies the connection to the voice server.

Returns:

The newly-created group member.

setAllowedMembers

public void setAllowedMembers(java.util.Set<java.lang.Long> allowedMembers)

Supply a list of oids of players allowed to be in the group

Specified by:

setAllowedMembers in interface VoiceGroup

Parameters:

allowedMembers - The set of oids of possible group members.

getAllowedMembers

public java.util.Set<java.lang.Long> getAllowedMembers()

Return the allowed members

Specified by:

getAllowedMembers in interface VoiceGroup

Returns:

A Set of allowed member oids.

addMember

public abstract GroupMember addMember(long memberOid,
                                      VoiceConnection memberCon,
                                      int priority,
                                      boolean allowedSpeaker)

Create a member with the given oid, and associate it with memberCon.

Specified by:

addMember in interface VoiceGroup

Parameters:

memberOid - The oid of the member.

memberCon - The VoiceConnection object connecting the voice server with the client

priority - The speaking priority that the member should be assigned; speakers with higher priorities will be heard over speakers with lower priorities.

allowedSpeaker - If true, the new member is allowed to speak in the group; if false they will not be heard by members by members of the group.

Returns:

The newly-created group member.

onAfterAddMember

public void onAfterAddMember(long memberOid,
                             long groupOid,
                             boolean allowedSpeaker,
                             byte micVoiceNumber,
                             boolean listenToYourself)

A call to this method is made after an addMember() operation.

Specified by:

onAfterAddMember in interface VoiceGroup

Parameters:

memberOid - The oid of the newly-created member

groupOid - The groupOid of the voice group.

allowedSpeaker - True if the member is allowed to speak; false otherwise.

micVoiceNumber - The voice number of the incoming voice packets. For now, this is always zero.

listenToYourself - True if the member wants his own voice frames sent back to him. This is only used for testing purposes.

isPositional

public abstract boolean isPositional()

Return true if the group is a positional group; that is, if membership in the group is determined by being near the listener, and the priority of speakers is determined by how near any speaker is.

Specified by:

isPositional in interface VoiceGroup

changeSpeaking

protected abstract void changeSpeaking(GroupMember speaker,
                                       boolean add)

Change a speaker from not speaking to speaking, or vice versa

Parameters:

speaker - A GroupMember instance whose speaking state is to be changed.

add - If true, change the speaker from not speaking to speaking, if false, from speaking to not speaking.

changeListening

protected abstract void changeListening(GroupMember listener,
                                        boolean add)

Change a listener from not listening to listening, or vice versa

Parameters:

listener - A GroupMember instance whose listening state is to be changed.

add - If true, change the listener from not listening to listening, if false, from listening to not listening.

recomputeListenerVoices

protected abstract void recomputeListenerVoices(GroupMember listener)

The set of speakers who should now be heard by this listener (may have) changed; send appropriate voice deallocates and allocates to reflect those changes

Parameters:

listener - A GroupMember instance whose voices will be recomputed.

removeMember

public boolean removeMember(long memberOid)

Sever all speaker/listener relationships involving the member, and remove the member identified by memberOid.

Specified by:

removeMember in interface VoiceGroup

Parameters:

memberOid - The oid of the member to be removed from the group.

Returns:

True member was found; false otherwise

onAfterRemoveMember

public void onAfterRemoveMember(long memberOid,
                                long groupOid,
                                boolean allowedSpeaker)

A call to this method is made after a removeMember() operation.

Specified by:

onAfterRemoveMember in interface VoiceGroup

Parameters:

memberOid - The oid of the newly-created member

groupOid - The groupOid of the voice group.

allowedSpeaker - True if the member is allowed to speak; false otherwise.

isMember

public GroupMember isMember(long memberOid)

Return the member identified by memberOid, or null if there is no such member. Does not need locking, since there are no modifications and the status could change immediately after the call anyway.

Specified by:

isMember in interface VoiceGroup

Parameters:

memberOid - The oid of the member to be returned

Returns:

The member with memberOid, or null if it doesn't exist.

getDefaultPriority

public int getDefaultPriority()

Return the default priority of members

Specified by:

getDefaultPriority in interface VoiceGroup

Returns:

The default priority of newly-created members

setAllowedSpeaker

public void setAllowedSpeaker(long memberOid,
                              boolean add)

Sets whether the member is allowed ot speak.

Specified by:

setAllowedSpeaker in interface VoiceGroup

Parameters:

memberOid - The oid of the member to change.

add - True if the member should be allowed to speak; false otherwise.

setAllowedSpeaker

protected void setAllowedSpeaker(GroupMember member,
                                 boolean add)

Change whether a member is allowed to speak or not, and if it was formerly speaking, sever it's speaker to listener relationships by sending voice channel deallocation messages.

Parameters:

member - The GroupMember instance to change.

add - True if the member should be allowed to speak; false otherwise.

isAllowedSpeaker

public boolean isAllowedSpeaker(long memberOid)

Does not need locking, since there are no modifications and the status could change immediately after the call anyway.

Specified by:

isAllowedSpeaker in interface VoiceGroup

Parameters:

memberOid - The oid of the member whose allowed speaker status will be returned.

Returns:

True if the member can be found in the group and is allowed to be a speaker; false otherwise.

setMemberSpeaking

public void setMemberSpeaking(long memberOid,
                              boolean add)

Change a member that is allowed to speak from not speaking to speaking, or vice versa, and do whatever voice deallocation and/or allocation is required as a result.

Specified by:

setMemberSpeaking in interface VoiceGroup

Parameters:

memberOid - The GroupMember instance to change.

add - True if the member should be allowed to speak; false otherwise.

isMemberSpeaking

public boolean isMemberSpeaking(long memberOid)

Does not need locking, since there are no modifications and the status could change immediately after the call anyway.

Specified by:

isMemberSpeaking in interface VoiceGroup

Parameters:

memberOid - The oid of the member whose speaking status will be returned.

Returns:

True if the member can be found in the group and is now speaking; false otherwise.

isListener

public boolean isListener(long memberOid)

Does not need locking, since there are no modifications and the status could change immediately after the call anyway.

Specified by:

isListener in interface VoiceGroup

Parameters:

memberOid - The oid of the member whose listening status will be returned.

Returns:

True if the member can be found in the group and is now listening to the group; false otherwise.

setListener

public void setListener(long memberOid,
                        boolean add)

Change the member with the given oid to be a listener if add is true, or not a listener if add is false. Sends out any required allocation or deallocation messages to adjust speaker/listener relationships.

Specified by:

setListener in interface VoiceGroup

Parameters:

memberOid - The oid of the member whose whose listening status should change.

add - If true, make the member a listener in the group, else stop the member listening.

setListener

public void setListener(GroupMember member,
                        boolean add)

Change the member supplied to be a listener if add is true, or not a listener if add is false. Sends out any required allocation or deallocation messages to adjust speaker/listener relationships.

Parameters:

member - The member whose whose listening status should change.

add - If true, make the member a listener in the group, else stop the member listening.

endListeningToSpeaker

protected void endListeningToSpeaker(GroupMember speaker,
                                     GroupMember listener,
                                     byte voiceNumber)

Terminate the voice channel, whose voice channel number is voiceNumber, between the given speaker and listener by sending a deallocate message to the listener's client.

Parameters:

speaker - The member that is the source of the voice channel.

listener - The member that will receive the voice channel deallocation message.

voiceNumber - The number of the voice channel opened to the client, unique within an single client.

eligibleSpeakerListenerPair

protected boolean eligibleSpeakerListenerPair(GroupMember speaker,
                                              GroupMember listener)

A default implementation of a filter that determines if we are allowed to form a voice channel from the given speaker to the given listener. This will likely be overriden by many virtual world builder.

Parameters:

speaker - The member that is the source of the voice channel.

listener - The member that will receive the voice channel deallocation message.

getMember

protected GroupMember getMember(long oid)

sendVoiceFrameToListeners

public void sendVoiceFrameToListeners(long speakerOid,
                                      multiverse.server.network.MVByteBuffer buf,
                                      byte opcode,
                                      int pktSize)

Send a voice frame originating with the speaker with the given oid, and contained in the first dataSize bytes of buf, to all eligible listeners

Specified by:

sendVoiceFrameToListeners in interface VoiceGroup

Parameters:

speakerOid - The oid of the speaker that is the source of the voice frame(s)

buf - The buffer containing data packet; typically a data aggregation packet

opcode - The opcode to use when sending the frame(s). Typically VoicePlugin.opcodeAggregatedData.

pktSize - The size of the payload.

recomputeVoicesFromSpeakerIterator

protected void recomputeVoicesFromSpeakerIterator(GroupMember listener,
                                                  java.util.Iterator<GroupMember> memberIterator,
                                                  int count)

This is central method that recalculates the voices that should be heard by a listener, based on a potential set of voices currently speaking, sending out allocations and deallocations as a result.

Parameters:

listener - The group member, currently a listener, that should have it's voice channels recomputed.

memberIterator - An iterator used to run down the group members in "priority order".

count - The number of elements from the iterator to consider.

addString

protected java.lang.String addString(boolean add)

Utility method used in logging.

toString

public java.lang.String toString()

Make a string

Overrides:

toString in class java.lang.Object