diff --git a/src/org/ice4j/ice/Agent.java b/src/org/ice4j/ice/Agent.java index 911e384..59ddc6c 100644 --- a/src/org/ice4j/ice/Agent.java +++ b/src/org/ice4j/ice/Agent.java @@ -81,6 +81,11 @@ public class Agent private final FoundationsRegistry foundationsRegistry = new FoundationsRegistry(); + /** + * Our internal nominator implementing several nomination strategies. + */ + private final DefaultNominator nominator = new DefaultNominator(this); + /** * the value of Ta as specified by the application or -1 * if non was specified and we should calculate one ourselves. @@ -1015,21 +1020,51 @@ public class Agent { Component parentComponent = validPair.getParentComponent(); IceMediaStream parentStream = parentComponent.getParentStream(); - CheckList checkList = parentStream.getCheckList(); - parentStream.addValidPair(validPair); + parentStream.addToValidList(validPair); + } + + /** + * Raises pair's nomination flag and schedules a triggered check. + * Applications only need to use this method if they disable this + * Agent's internal nomination and implement their own nomination + * strategy. + * + * @param pair the {@link CandidatePair} that we'd like to nominate and that + * we'd like to schedule a triggered check for. + * + * @throws IllegalStateException if this Agent is not a controlling + * agent and can therefore not nominate pairs. + * + * @see Agent#setAutoNominationEnabled(boolean) + */ + public void nominate(CandidatePair pair) + throws IllegalStateException + { + if(! isControlling() ) + throw new IllegalStateException("Only controlling agents can " + +"nominate pairs"); + + Component parentComponent = pair.getParentComponent(); + IceMediaStream parentStream = parentComponent.getParentStream(); + CheckList checkList = parentStream.getCheckList(); //If the pair is not already nominated and if its parent component //does not already contain a nominated pair - nominate it. - if(!validPair.isNominated() + if(!pair.isNominated() && !checkList.containsNomineeForComponent(parentComponent)) { - validPair.nominate(); - validPair.getParentComponent().getParentStream() - .getCheckList().scheduleTriggeredCheck(validPair); + pair.nominate(); + pair.getParentComponent().getParentStream() + .getCheckList().scheduleTriggeredCheck(pair); } } + public void setNominationStrategy() + { + + } + /** * Indicates that we have received a response to a request that either * contained the USE-CANDIDATE attribute or was triggered by an diff --git a/src/org/ice4j/ice/CheckList.java b/src/org/ice4j/ice/CheckList.java index 683571f..7b87cac 100644 --- a/src/org/ice4j/ice/CheckList.java +++ b/src/org/ice4j/ice/CheckList.java @@ -6,6 +6,7 @@ */ package org.ice4j.ice; +import java.beans.*; import java.util.*; /** @@ -41,18 +42,26 @@ public class CheckList = new LinkedList(); /** - * A name for this check list which we use for debugging purposes + * A reference to the {@link IceMediaStream} that we belong to. */ - private final String name; + private final IceMediaStream parentStream; + + /** + * Contains {@link PropertyChangeListener}s registered with this {@link + * Agent} and following its changes of state. + */ + private List stateListeners + = new LinkedList(); /** * Creates a check list with the specified name. * - * @param name the name of the check list. + * @param parentStream a reference to the parent {@link IceMediaStream} + * that created us and that we belong to. */ - protected CheckList(String name) + protected CheckList(IceMediaStream parentStream) { - this.name = name; + this.parentStream = parentStream; } /** @@ -68,11 +77,14 @@ public class CheckList /** * Sets the state of this list. * - * @param state the CheckListState for this list. + * @param newState the CheckListState for this list. */ - protected void setState(CheckListState state) + protected void setState(CheckListState newState) { - this.state = state; + CheckListState oldState = this.state; + this.state = newState; + + fireStateChange(oldState, newState); } /** @@ -362,7 +374,7 @@ public class CheckList */ public String getName() { - return name; + return parentStream.getName(); } /** @@ -388,4 +400,60 @@ public class CheckList return false; } + + /** + * Adds l to the list of listeners tracking changes of the + * {@link CheckListState} of this CheckList + * + * @param l the listener to register. + */ + public void addStateChangeListener(PropertyChangeListener l) + { + synchronized(stateListeners) + { + if(!stateListeners.contains(l)) + this.stateListeners.add(l); + } + } + + /** + * Removes l from the list of listeners tracking changes of the + * {@link CheckListState} of this CheckList + * + * @param l the listener to remove. + */ + public void removeStateChangeListener(PropertyChangeListener l) + { + synchronized(stateListeners) + { + this.stateListeners.remove(l); + } + } + + /** + * Creates a new {@link PropertyChangeEvent} and delivers it to all + * currently registered state listeners. + * + * @param oldState the {@link CheckListState} we had before the change + * @param newState the {@link CheckListState} we had after the change + */ + private void fireStateChange(CheckListState oldState, + CheckListState newState) + { + List listenersCopy; + + synchronized(stateListeners) + { + listenersCopy + = new LinkedList(stateListeners); + } + + PropertyChangeEvent evt = new PropertyChangeEvent( + this, "CheckListState", oldState, newState); + + for(PropertyChangeListener l : listenersCopy) + { + l.propertyChange(evt); + } + } } diff --git a/src/org/ice4j/ice/DefaultNominator.java b/src/org/ice4j/ice/DefaultNominator.java new file mode 100644 index 0000000..5dad18e --- /dev/null +++ b/src/org/ice4j/ice/DefaultNominator.java @@ -0,0 +1,29 @@ +/* + * ice4j, the OpenSource Java Solution for NAT and Firewall Traversal. + * Maintained by the SIP Communicator community (http://sip-communicator.org). + * + * Distributable under LGPL license. See terms of license at gnu.org. + */ +package org.ice4j.ice; + +import java.beans.*; + +/** + * Implements nomination strategies + * @author Emil Ivov + */ +public class DefaultNominator + implements PropertyChangeListener +{ + private final Agent parentAgent; + + public DefaultNominator(Agent parentAgent) + { + this.parentAgent = parentAgent; + } + + public void propertyChange(PropertyChangeEvent evt) + { + + } +} diff --git a/src/org/ice4j/ice/IceMediaStream.java b/src/org/ice4j/ice/IceMediaStream.java index fce9d15..86e8b78 100644 --- a/src/org/ice4j/ice/IceMediaStream.java +++ b/src/org/ice4j/ice/IceMediaStream.java @@ -7,6 +7,7 @@ */ package org.ice4j.ice; +import java.beans.*; import java.util.*; import java.util.logging.*; @@ -69,6 +70,19 @@ public class IceMediaStream */ private final Agent parentAgent; + /** + * The property name that we use when delivering events notifying listeners + * of newly validated pairs. + */ + public static final String PROPERTY_PAIR_VALIDATED = "PairValidated"; + + /** + * Contains {@link PropertyChangeListener}s registered with this {@link + * Agent} and following the various events it may be generating. + */ + private List streamListeners + = new LinkedList(); + /** * The maximum number of candidate pairs that we should have in our check * list. This value depends on the total number of media streams which is @@ -91,7 +105,7 @@ public class IceMediaStream { this.name = name; this.parentAgent = parentAgent; - checkList = new CheckList(name); + checkList = new CheckList(this); } /** @@ -552,7 +566,7 @@ public class IceMediaStream * * @param pair the {@link CandidatePair} to add to our valid list. */ - protected void addValidPair(CandidatePair pair) + protected void addToValidList(CandidatePair pair) { synchronized (validList) { @@ -560,6 +574,8 @@ public class IceMediaStream if(!validList.contains(pair)) validList.add(pair); } + + fireStateChange(PROPERTY_PAIR_VALIDATED, pair, pair); } /** @@ -653,4 +669,86 @@ public class IceMediaStream return null; } + + /** + * Adds l to the list of listeners registered for property changes. + * + * @param l the listener to register. + */ + public void addStreamChangeListener(PropertyChangeListener l) + { + synchronized(streamListeners) + { + if(!streamListeners.contains(l)) + this.streamListeners.add(l); + } + } + + /** + * Removes l from the list of listeners registered for property + * changes. + * + * @param l the listener to remove. + */ + public void removeStateChangeListener(PropertyChangeListener l) + { + synchronized(streamListeners) + { + this.streamListeners.remove(l); + } + } + + /** + * Creates a new {@link PropertyChangeEvent} and delivers it to all + * currently registered state listeners. + * + * @param propertyName the name of the event we'd like to fire. + * @param oldValue the old value of the property that changed. + * @param newValue the new value of the property that changed. + */ + private void fireStateChange(String propertyName, + Object oldValue, + Object newValue) + { + List listenersCopy; + + synchronized(streamListeners) + { + listenersCopy + = new LinkedList(streamListeners); + } + + PropertyChangeEvent evt = new PropertyChangeEvent( + this, "CheckListState", oldValue, newValue); + + for(PropertyChangeListener l : listenersCopy) + { + l.propertyChange(evt); + } + } + + /** + * Returns the {@link CandidatePair} from component that's + * currently first in our valid list and that is therefore with the highest + * priority. + * + * @param component the {@link Component} whose highest priority valid + * {@link CandidatePair} we are looking for. + * + * @return the {@link CandidatePair} with the highest priority in our + * valid list or null if our valid list is still empty. + */ + public CandidatePair getFirstValidPair(Component component) + { + synchronized(validList) + { + for(CandidatePair pair : validList) + { + if (pair.getParentComponent() == component) + return pair; + } + } + + return null; + } } diff --git a/src/org/ice4j/ice/NominationStrategy.java b/src/org/ice4j/ice/NominationStrategy.java new file mode 100644 index 0000000..8fc7789 --- /dev/null +++ b/src/org/ice4j/ice/NominationStrategy.java @@ -0,0 +1,66 @@ +/* + * ice4j, the OpenSource Java Solution for NAT and Firewall Traversal. + * Maintained by the SIP Communicator community (http://sip-communicator.org). + * + * Distributable under LGPL license. See terms of license at gnu.org. + */ +package org.ice4j.ice; + +/** + * Contains the nomination strategies currently supported by this + * implementation's {@link DefaultNominator} class. Applications can either + * pick one of these strategies or select NONE in case they want to + * handle nominations themselves. + *

+ * Note that NominationStrategies are an ice4j concept and they are not + * mentioned in RFC 5245. + * + * @author Emil Ivov + */ +public enum NominationStrategy +{ + /** + * The strategy consists in nominating the first candidate pair that's + * confirmed as valid. + */ + NOMINATE_FIRST_VALID("NominateFirstValid"), + + /** + * The strategy consists in nominating the highest priority valid pair once + * all checks in a list have completed. + */ + NOMINATE_HIGHEST_PRIO("NominateHighestPriority"), + + /** + * The strategy consists in nominating the pair that showed the best + * shortest round trip time once all checks in a list completed. + */ + NOMINATE_BEST_RTT("NominateBestRTT"); + + /** + * The name of this strategy. + */ + private final String strategyName; + + /** + * Creates a NominationStrategy instance with the specified name. + * + * @param name the name of the NominationStrategy that we'd like + * to create. + */ + private NominationStrategy(String name) + { + this.strategyName = name; + } + + /** + * Returns the name of this NominationStrategy. + * + * @return the name of this NominationStrategy. + */ + @Override + public String toString() + { + return strategyName; + } +}