Adds a nomination utility with, currently, two nomination strategies.

This commit is contained in:
emcho 2010-05-18 07:23:41 +00:00
parent b8c6760b96
commit 95a59dbb2a
7 changed files with 134 additions and 30 deletions

View File

@ -114,6 +114,8 @@ public class StackProperties
= "org.ice4j.TERMINATION_DELAY"; = "org.ice4j.TERMINATION_DELAY";
/** /**
* THIS PROPERTY IS CURRENTLY UNUSED. IF YOU WANT TO SPEED UP NOMINATIONS
* THEN CONSIDER SPEEDING UP TRANSACTION FAILURE FOR THE TIME BEING.
* The maximum number of milliseconds that we should wait for a check list * The maximum number of milliseconds that we should wait for a check list
* to complete before nominating one of its valid pairs (unless there are * to complete before nominating one of its valid pairs (unless there are
* none in which case we may have to wait until one appears or the whole * none in which case we may have to wait until one appears or the whole

View File

@ -235,7 +235,7 @@ public class CandidatePair
* {@link CandidatePairState#IN_PROGRESS} or a non-<tt>null</tt> for any * {@link CandidatePairState#IN_PROGRESS} or a non-<tt>null</tt> for any
* other state would cause an {@link IllegalArgumentException} to be thrown. * other state would cause an {@link IllegalArgumentException} to be thrown.
* *
* @param state the state that this candidate pair is to enter. * @param newState the state that this candidate pair is to enter.
* @param tranID the {@link TransactionID} that we are using for the * @param tranID the {@link TransactionID} that we are using for the
* connectivity check in case we are entering the <tt>In-Progress</tt> * connectivity check in case we are entering the <tt>In-Progress</tt>
* state and <tt>null</tt> otherwise. * state and <tt>null</tt> otherwise.
@ -243,13 +243,14 @@ public class CandidatePair
* @throws IllegalArgumentException if state is {@link CandidatePairState * @throws IllegalArgumentException if state is {@link CandidatePairState
* #IN_PROGRESS} and <tt>tranID</tt> is <tt>null</tt>. * #IN_PROGRESS} and <tt>tranID</tt> is <tt>null</tt>.
*/ */
private synchronized void setState(CandidatePairState state, private synchronized void setState(CandidatePairState newState,
TransactionID tranID) TransactionID tranID)
throws IllegalArgumentException throws IllegalArgumentException
{ {
this.state = state; CandidatePairState oldState = this.state;
this.state = newState;
if(state != CandidatePairState.IN_PROGRESS) if(newState != CandidatePairState.IN_PROGRESS)
{ {
if (tranID != null) if (tranID != null)
throw new IllegalArgumentException( throw new IllegalArgumentException(
@ -266,6 +267,9 @@ public class CandidatePair
this.connCheckTranID = tranID; this.connCheckTranID = tranID;
getParentComponent().getParentStream().firePairPropertyChange(
this, IceMediaStream.PROPERTY_PAIR_STATE_CHANGED,
oldState, newState);
} }
/** /**
@ -523,6 +527,8 @@ public class CandidatePair
public void nominate() public void nominate()
{ {
this.isNominated = true; this.isNominated = true;
getParentComponent().getParentStream().firePairPropertyChange(this,
IceMediaStream.PROPERTY_PAIR_NOMINATED, false, true);
} }
/** /**
@ -556,5 +562,7 @@ public class CandidatePair
protected void validate() protected void validate()
{ {
this.isValid = true; this.isValid = true;
getParentComponent().getParentStream().firePairPropertyChange(this,
IceMediaStream.PROPERTY_PAIR_VALIDATED, false, true);
} }
} }

View File

@ -186,7 +186,7 @@ public class CheckList
* @return <tt>true</tt> if this list is active and <tt>false</tt> * @return <tt>true</tt> if this list is active and <tt>false</tt>
* otherwise. * otherwise.
*/ */
protected synchronized boolean isActive() public synchronized boolean isActive()
{ {
for (CandidatePair pair : this) for (CandidatePair pair : this)
{ {
@ -196,6 +196,25 @@ public class CheckList
return false; return false;
} }
/**
* Determines whether all checks in this <tt>CheckList</tt> have ended one
* way or another.
*
* @return <tt>true</tt> if all checks for pairs in this list have either
* succeeded or failed (but non are are currently waiting or in progress)
* or <tt>false</tt> otherwise..
*/
public synchronized boolean allChecksCompleted()
{
for (CandidatePair pair : this)
{
if (pair.getState() != CandidatePairState.SUCCEEDED
&& pair.getState() != CandidatePairState.FAILED)
return false;
}
return true;
}
/** /**
* Determines whether this <tt>CheckList</tt> can be considered frozen. * Determines whether this <tt>CheckList</tt> can be considered frozen.
* RFC 5245 says: a check list with all pairs Frozen is called a frozen * RFC 5245 says: a check list with all pairs Frozen is called a frozen
@ -204,7 +223,7 @@ public class CheckList
* @return <tt>true</tt> if all pairs in this list are frozen and * @return <tt>true</tt> if all pairs in this list are frozen and
* <tt>false</tt> otherwise. * <tt>false</tt> otherwise.
*/ */
protected synchronized boolean isFrozen() public synchronized boolean isFrozen()
{ {
for (CandidatePair pair : this) for (CandidatePair pair : this)
{ {
@ -462,4 +481,16 @@ public class CheckList
l.propertyChange(evt); l.propertyChange(evt);
} }
} }
/**
* Returns a reference to the {@link IceMediaStream} that created and that
* maintains this check list.
*
* @return a reference to the {@link IceMediaStream} that this list belongs
* to.
*/
public IceMediaStream getParentStream()
{
return parentStream;
}
} }

View File

@ -372,14 +372,14 @@ class ConnectivityCheckClient
validRemoteCandidate); validRemoteCandidate);
} }
if(! validPair.isValid())
parentAgent.validatePair(validPair);
//The agent sets the state of the pair that *generated* the check to //The agent sets the state of the pair that *generated* the check to
//Succeeded. Note that, the pair which *generated* the check may be //Succeeded. Note that, the pair which *generated* the check may be
//different than the valid pair constructed above //different than the valid pair constructed above
checkedPair.setStateSucceeded(); checkedPair.setStateSucceeded();
if(! validPair.isValid())
parentAgent.validatePair(validPair);
//The agent changes the states for all other Frozen pairs for the //The agent changes the states for all other Frozen pairs for the
//same media stream and same foundation to Waiting. //same media stream and same foundation to Waiting.
IceMediaStream parentStream = checkedPair.getParentComponent() IceMediaStream parentStream = checkedPair.getParentComponent()
@ -406,7 +406,8 @@ class ConnectivityCheckClient
{ {
for(CandidatePair pair : checkList) for(CandidatePair pair : checkList)
{ {
if (parentStream.validListContainsFoundation(pair.getFoundation()) if (parentStream.validListContainsFoundation(
pair.getFoundation())
&& pair.getState() == CandidatePairState.FROZEN) && pair.getState() == CandidatePairState.FROZEN)
{ {
pair.setStateWaiting(); pair.setStateWaiting();

View File

@ -61,24 +61,74 @@ public class DefaultNominator
for(IceMediaStream stream : streams) for(IceMediaStream stream : streams)
{ {
stream.addStreamChangeListener(this); stream.addPairChangeListener(this);
stream.getCheckList().addStateChangeListener(this); stream.getCheckList().addStateChangeListener(this);
} }
} }
if (!parentAgent.isControlling()) if (!parentAgent.isControlling() //CONTROLLED agents cannot nominate
|| strategy == NominationStrategy.NONE)
{ {
//CONTROLLED agents cannot nominate pairs
return; return;
} }
if(strategy == NominationStrategy.NOMINATE_FIRST_VALID)
strategyNominateFirstValid(evt);
else if (strategy == NominationStrategy.NOMINATE_HIGHEST_PRIO)
strategyNominateHighestPrio(evt);
}
/**
* Implements a basic nomination strategy that consists in nominating the
* first pair that has become valid for a check list.
*
* @param evt the {@link PropertyChangeEvent} containing the pair which
* has been validated.
*/
private void strategyNominateFirstValid(PropertyChangeEvent evt)
{
if(IceMediaStream.PROPERTY_PAIR_VALIDATED.equals(evt.getPropertyName())) if(IceMediaStream.PROPERTY_PAIR_VALIDATED.equals(evt.getPropertyName()))
{ {
CandidatePair validPair = (CandidatePair)evt.getNewValue(); CandidatePair validPair = (CandidatePair)evt.getSource();
parentAgent.nominate(validPair); parentAgent.nominate(validPair);
} }
} }
/**
* Implements a nomination strategy that allows checks for several (or all)
* pairs in a check list to conclude before nominating the one with the
* highest priority.
*
* @param evt the {@link PropertyChangeEvent} containing the new state and
* the source {@link CheckList}.
*/
private void strategyNominateHighestPrio(PropertyChangeEvent evt)
{
String propName = evt.getPropertyName();
if(IceMediaStream.PROPERTY_PAIR_VALIDATED.equals(propName)
|| (IceMediaStream.PROPERTY_PAIR_STATE_CHANGED.equals(propName)
&& ((CandidatePairState)evt.getNewValue())
== CandidatePairState.FAILED))
{
CandidatePair validPair = (CandidatePair)evt.getSource();
Component parentComponent = validPair.getParentComponent();
IceMediaStream parentStream = parentComponent.getParentStream();
CheckList parentCheckList = parentStream.getCheckList();
if(!parentCheckList.allChecksCompleted())
return;
List<Component> components = parentStream.getComponents();
for(Component component : components)
{
CandidatePair pair = parentStream.getValidPair(component);
if(pair != null)
parentAgent.nominate(pair);
}
}
}
/** /**
* The {@link NominationStrategy} that this nominator should use when * The {@link NominationStrategy} that this nominator should use when

View File

@ -76,6 +76,18 @@ public class IceMediaStream
*/ */
public static final String PROPERTY_PAIR_VALIDATED = "PairValidated"; public static final String PROPERTY_PAIR_VALIDATED = "PairValidated";
/**
* The property name that we use when delivering events notifying listeners
* that a pair has changed states..
*/
public static final String PROPERTY_PAIR_STATE_CHANGED = "PairStateChanged";
/**
* The property name that we use when delivering events notifying listeners
* of newly nominated pairs.
*/
public static final String PROPERTY_PAIR_NOMINATED = "PairNominated";
/** /**
* Contains {@link PropertyChangeListener}s registered with this {@link * Contains {@link PropertyChangeListener}s registered with this {@link
* Agent} and following the various events it may be generating. * Agent} and following the various events it may be generating.
@ -173,7 +185,7 @@ public class IceMediaStream
* @return the <tt>Component</tt> with the specified <tt>id</tt> or * @return the <tt>Component</tt> with the specified <tt>id</tt> or
* <tt>null</tt> if no such component exists in this stream. * <tt>null</tt> if no such component exists in this stream.
*/ */
public Component getComponnet(int id) public Component getComponent(int id)
{ {
synchronized(components) synchronized(components)
{ {
@ -570,12 +582,11 @@ public class IceMediaStream
{ {
synchronized (validList) synchronized (validList)
{ {
pair.validate();
if(!validList.contains(pair)) if(!validList.contains(pair))
validList.add(pair); validList.add(pair);
} }
fireStateChange(PROPERTY_PAIR_VALIDATED, pair, pair); pair.validate();
} }
/** /**
@ -671,11 +682,14 @@ public class IceMediaStream
} }
/** /**
* Adds <tt>l</tt> to the list of listeners registered for property changes. * Adds <tt>l</tt> to the list of listeners registered for property changes
* if {@link CandidatePair}s. We add such listeners in the stream, rather
* than having them in the candidate pair itself, because we don't want all
* pairs to keep lists of references to the same listeners.
* *
* @param l the listener to register. * @param l the listener to register.
*/ */
public void addStreamChangeListener(PropertyChangeListener l) public void addPairChangeListener(PropertyChangeListener l)
{ {
synchronized(streamListeners) synchronized(streamListeners)
{ {
@ -690,7 +704,7 @@ public class IceMediaStream
* *
* @param l the listener to remove. * @param l the listener to remove.
*/ */
public void removeStateChangeListener(PropertyChangeListener l) public void removePairStateChangeListener(PropertyChangeListener l)
{ {
synchronized(streamListeners) synchronized(streamListeners)
{ {
@ -702,13 +716,15 @@ public class IceMediaStream
* Creates a new {@link PropertyChangeEvent} and delivers it to all * Creates a new {@link PropertyChangeEvent} and delivers it to all
* currently registered state listeners. * currently registered state listeners.
* *
* @param propertyName the name of the event we'd like to fire. * @param source the {@link CandidatePair} whose property has just changed.
* @param propertyName the name of the property that changed.
* @param oldValue the old value of the property that changed. * @param oldValue the old value of the property that changed.
* @param newValue the new value of the property that changed. * @param newValue the new value of the property that changed.
*/ */
private void fireStateChange(String propertyName, protected void firePairPropertyChange(CandidatePair source,
Object oldValue, String propertyName,
Object newValue) Object oldValue,
Object newValue)
{ {
List<PropertyChangeListener> listenersCopy; List<PropertyChangeListener> listenersCopy;
@ -719,7 +735,7 @@ public class IceMediaStream
} }
PropertyChangeEvent evt = new PropertyChangeEvent( PropertyChangeEvent evt = new PropertyChangeEvent(
this, PROPERTY_PAIR_VALIDATED, oldValue, newValue); source, PROPERTY_PAIR_VALIDATED, oldValue, newValue);
for(PropertyChangeListener l : listenersCopy) for(PropertyChangeListener l : listenersCopy)
{ {

View File

@ -6,7 +6,6 @@
*/ */
package org.ice4j.ice; package org.ice4j.ice;
import org.ice4j.*;
/** /**
* Contains the nomination strategies currently supported by this * Contains the nomination strategies currently supported by this
@ -35,10 +34,7 @@ public enum NominationStrategy
/** /**
* The strategy consists in nominating the highest priority valid pair once * The strategy consists in nominating the highest priority valid pair once
* all checks in a list have completed, or after the nomination timer has * all checks in a list have completed.
* fired for that check list, whichever happens first. The value of the
* nomination timer (in ms) is defined by the {@link StackProperties#
* NOMINATION_TIMER} property.
*/ */
NOMINATE_HIGHEST_PRIO("NominateHighestPriority"), NOMINATE_HIGHEST_PRIO("NominateHighestPriority"),