CandidatePair (ice4j 2.0.0-SNAPSHOT API)

java.lang.Object
- org.ice4j.ice.CandidatePair

All Implemented Interfaces:

Comparable<CandidatePair>
```
public class CandidatePair
extends Object
implements Comparable<CandidatePair>
```
CandidatePairs map local to remote Candidates so that they could be added to check lists. Connectivity in ICE is always verified by pairs: i.e. STUN packets are sent from the local candidate of a pair to the remote candidate of a pair. To see which pairs work, an agent schedules a series of ConnectivityChecks. Each check is a STUN request/response transaction that the client will perform on a particular candidate pair by sending a STUN request from the local candidate to the remote candidate.

Author:

Emil Ivov, Lyubomir Marinov, Boris Grozev

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CandidatePair.PairComparator
A Comparator using the compareTo method of the CandidatePair

Nested Classes
Modifier and Type	Class and Description
`static class`	`CandidatePair.PairComparator` A `Comparator` using the `compareTo` method of the `CandidatePair`

Field Summary

Fields
Modifier and Type	Field and Description
`static CandidatePair.PairComparator`	`comparator` A `Comparator` using the `compareTo` method of the `CandidatePair`.
`private TransactionID`	`connCheckTranID` The `TransactionID` of the client transaction for a connectivity check over this pair in case it is in the `CandidatePairState.IN_PROGRESS` state.
`static long`	`CONSENT_FRESHNESS_UNKNOWN` The value of the `consentFreshness` property of `CandidatePair` which indicates that the time in milliseconds of the latest consent freshness confirmation is unknown.
`private long`	`consentFreshness` The time in milliseconds of the latest consent freshness confirmation.
`private boolean`	`isNominated` If a valid candidate pair has its nominated flag set, it means that it may be selected by ICE for sending and receiving media.
`private boolean`	`isValid` Indicates whether this `CandidatePair` is on any of this agent's valid pair lists.
`private LocalCandidate`	`localCandidate` The local candidate of this pair.
`private static long`	`MATH_POW_2_32` The value of `Math.pow(2, 32)` calculated once for the purposes of optimizing performance.
`private long`	`priority` Priority of the candidate-pair
`private RemoteCandidate`	`remoteCandidate` The remote candidate of this pair.
`private CandidatePairState`	`state` Each candidate pair has a state that is assigned once the check list for each media stream has been computed.
`private boolean`	`useCandidate` A flag indicating whether we have seen an incoming check request that contained the USE-CANDIDATE attribute for this pair.
`private boolean`	`useCandidateSent` A flag indicating whether we have sent a check request that contained the USE-CANDIDATE attribute for this pair.

Constructor Summary

Constructors
Constructor and Description
`CandidatePair(LocalCandidate localCandidate, RemoteCandidate remoteCandidate)` Creates a `CandidatePair` instance mapping `localCandidate` to `remoteCandidate`.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`int`	`compareTo(CandidatePair candidatePair)` Compares this `CandidatePair` with the specified object for order.
`protected void`	`computePriority()` A candidate pair priority is computed the following way: Let G be the priority for the candidate provided by the controlling agent.
`boolean`	`equals(Object obj)` Compares this `CandidatePair` to `obj` and returns `true` if pairs have equal local and equal remote candidates and `false` otherwise.
`TransactionID`	`getConnectivityCheckTransaction()` Returns the `TransactionID` used in the connectivity check associated with this `CandidatePair` when it's in the `CandidatePairState.IN_PROGRESS` or `null` if it's in any other state.
`long`	`getConsentFreshness()` Gets the time in milliseconds of the latest consent freshness confirmation.
`Candidate<?>`	`getControlledAgentCandidate()` Returns the candidate in this pair that belongs to the controlled agent.
`Candidate<?>`	`getControllingAgentCandidate()` Returns the candidate in this pair that belongs to the controlling agent.
`DatagramSocket`	`getDatagramSocket()` Deprecated.
`String`	`getFoundation()` Returns the foundation of this `CandidatePair`.
`IceSocketWrapper`	`getIceSocketWrapper()` Deprecated.
`LocalCandidate`	`getLocalCandidate()` Returns the `LocalCandidate` of this `CandidatePair`.
`Component`	`getParentComponent()` Returns the `Component` that this pair belongs to.
`long`	`getPriority()` Returns the priority of this pair.
`RemoteCandidate`	`getRemoteCandidate()` Returns the remote candidate of this `CandidatePair`.
`Socket`	`getSocket()` Deprecated.
`CandidatePairState`	`getState()` Returns the state of this `CandidatePair`.
`int`	`hashCode()`
`boolean`	`isFrozen()` Determines whether this candidate pair is frozen or not.
`boolean`	`isNominated()` Returns the value of this pair's nominated flag.
`boolean`	`isValid()` Returns `true` if this pair has been confirmed by a connectivity check response and `false` otherwise.
`void`	`nominate()` Sets this pair's nominated flag to `true`.
`(package private) void`	`setConsentFreshness()` Sets the time in milliseconds of the latest consent freshness confirmation to now.
`(package private) void`	`setConsentFreshness(long consentFreshness)` Sets the time in milliseconds of the latest consent freshness confirmation to a specific time.
`protected void`	`setLocalCandidate(LocalCandidate localCnd)` Sets the `LocalCandidate` of this `CandidatePair`.
`protected void`	`setRemoteCandidate(RemoteCandidate remoteCnd)` Sets the `RemoteCandidate` of this `CandidatePair`.
`private void`	`setState(CandidatePairState newState, TransactionID tranID)` Sets the `CandidatePairState` of this pair to `state`.
`void`	`setStateFailed()` Sets the `CandidatePairState` of this pair to `CandidatePairState.FAILED`.
`void`	`setStateFrozen()` Sets the `CandidatePairState` of this pair to `CandidatePairState.FROZEN`.
`void`	`setStateInProgress(TransactionID tranID)` Sets the `CandidatePairState` of this pair to `CandidatePairState.FROZEN`.
`void`	`setStateSucceeded()` Sets the `CandidatePairState` of this pair to `CandidatePairState.SUCCEEDED`.
`void`	`setStateWaiting()` Sets the `CandidatePairState` of this pair to `CandidatePairState.WAITING`.
`void`	`setUseCandidateReceived()` Raises the `useCandidate` flag for this pair.
`void`	`setUseCandidateSent()` Raises the `useCandidateSent` flag for this pair.
`String`	`toShortString()` Returns a short String representation of this `CandidatePair`.
`String`	`toString()` Returns a String representation of this `CandidatePair`.
`boolean`	`useCandidateReceived()` Returns `true` if someone has previously raised this pair's `useCandidate` flag and `false` otherwise.
`boolean`	`useCandidateSent()` Returns `true` if someone has previously raised this pair's `useCandidateSent` flag and `false` otherwise.
`protected void`	`validate()` Marks this pair as valid.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - CONSENT_FRESHNESS_UNKNOWN
```
public static final long CONSENT_FRESHNESS_UNKNOWN
```
    The value of the consentFreshness property of CandidatePair which indicates that the time in milliseconds of the latest consent freshness confirmation is unknown.
    
    See Also:
    
    Constant Field Values
  - MATH_POW_2_32
```
private static final long MATH_POW_2_32
```
    The value of Math.pow(2, 32) calculated once for the purposes of optimizing performance.
    
    See Also:
    
    Constant Field Values
  - comparator
```
public static final CandidatePair.PairComparator comparator
```
    A Comparator using the compareTo method of the CandidatePair.
  - localCandidate
```
private LocalCandidate localCandidate
```
    The local candidate of this pair.
  - remoteCandidate
```
private RemoteCandidate remoteCandidate
```
    The remote candidate of this pair.
  - priority
```
private long priority
```
    Priority of the candidate-pair
  - useCandidate
```
private boolean useCandidate
```
    A flag indicating whether we have seen an incoming check request that contained the USE-CANDIDATE attribute for this pair.
  - useCandidateSent
```
private boolean useCandidateSent
```
    A flag indicating whether we have sent a check request that contained the USE-CANDIDATE attribute for this pair. It is used in GTalk compatibility mode as it lacks USE-CANDIDATE.
  - isValid
```
private boolean isValid
```
    Indicates whether this CandidatePair is on any of this agent's valid pair lists.
  - isNominated
```
private boolean isNominated
```
    If a valid candidate pair has its nominated flag set, it means that it may be selected by ICE for sending and receiving media.
  - state
```
private CandidatePairState state
```
    Each candidate pair has a state that is assigned once the check list for each media stream has been computed. The ICE RFC defines five potential values that the state can have and they are all represented in the CandidatePairState enumeration. The ICE spec stipulates that the first step of the state initialization process is: The agent sets all of the pairs in each check list to the Frozen state, and hence our default state.
  - connCheckTranID
```
private TransactionID connCheckTranID
```
    The TransactionID of the client transaction for a connectivity check over this pair in case it is in the CandidatePairState.IN_PROGRESS state.
  - consentFreshness
```
private long consentFreshness
```
    The time in milliseconds of the latest consent freshness confirmation.
- Constructor Detail
  - CandidatePair
```
public CandidatePair(LocalCandidate localCandidate,
                     RemoteCandidate remoteCandidate)
```
    Creates a CandidatePair instance mapping localCandidate to remoteCandidate.
    
    Parameters:
    
    localCandidate - the local candidate of the pair.
    
    remoteCandidate - the remote candidate of the pair.
- Method Detail
  - getFoundation
```
public String getFoundation()
```
    Returns the foundation of this CandidatePair. The foundation of a CandidatePair is just the concatenation of the foundations of its two candidates. Initially, only the candidate pairs with unique foundations are tested. The other candidate pairs are marked "frozen". When the connectivity checks for a candidate pair succeed, the other candidate pairs with the same foundation are unfrozen. This avoids repeated checking of components which are superficially more attractive but in fact are likely to fail.
    
    Returns:
    
    the foundation of this candidate pair, which is a concatenation of the foundations of the remote and local candidates.
  - getLocalCandidate
```
public LocalCandidate getLocalCandidate()
```
    Returns the LocalCandidate of this CandidatePair.
    
    Returns:
    
    the local Candidate of this CandidatePair.
  - setLocalCandidate
```
protected void setLocalCandidate(LocalCandidate localCnd)
```
    Sets the LocalCandidate of this CandidatePair.
    
    Parameters:
    
    localCnd - the local Candidate of this CandidatePair.
  - getRemoteCandidate
```
public RemoteCandidate getRemoteCandidate()
```
    Returns the remote candidate of this CandidatePair.
    
    Returns:
    
    the remote Candidate of this CandidatePair.
  - setRemoteCandidate
```
protected void setRemoteCandidate(RemoteCandidate remoteCnd)
```
    Sets the RemoteCandidate of this CandidatePair.
    
    Parameters:
    
    remoteCnd - the local Candidate of this CandidatePair.
  - getState
```
public CandidatePairState getState()
```
    Returns the state of this CandidatePair. Each candidate pair has a state that is assigned once the check list for each media stream has been computed. The ICE RFC defines five potential values that the state can have. They are represented here with the CandidatePairState enumeration.
    
    Returns:
    
    the CandidatePairState that this candidate pair is currently in.
  - setStateFailed
```
public void setStateFailed()
```
    Sets the CandidatePairState of this pair to CandidatePairState.FAILED. This method should only be called by the ICE agent, during the execution of the ICE procedures.
  - setStateFrozen
```
public void setStateFrozen()
```
    Sets the CandidatePairState of this pair to CandidatePairState.FROZEN. This method should only be called by the ICE agent, during the execution of the ICE procedures.
  - setStateInProgress
```
public void setStateInProgress(TransactionID tranID)
```
    Sets the CandidatePairState of this pair to CandidatePairState.FROZEN. This method should only be called by the ICE agent, during the execution of the ICE procedures.
    
    Parameters:
    
    tranID - the TransactionID that we are using for the connectivity check in case we are entering the In-Progress state and null otherwise.
  - setStateSucceeded
```
public void setStateSucceeded()
```
    Sets the CandidatePairState of this pair to CandidatePairState.SUCCEEDED. This method should only be called by the ICE agent, during the execution of the ICE procedures.
  - setStateWaiting
```
public void setStateWaiting()
```
    Sets the CandidatePairState of this pair to CandidatePairState.WAITING. This method should only be called by the ICE agent, during the execution of the ICE procedures.
  - setState
```
private void setState(CandidatePairState newState,
                      TransactionID tranID)
               throws IllegalArgumentException
```
    Sets the CandidatePairState of this pair to state. This method should only be called by the ice agent, during the execution of the ICE procedures. Note that passing a null transaction for the CandidatePairState.IN_PROGRESS or a non-null for any other state would cause an IllegalArgumentException to be thrown.
    
    Parameters:
    
    newState - the state that this candidate pair is to enter.
    
    tranID - the TransactionID that we are using for the connectivity check in case we are entering the In-Progress state and null otherwise.
    
    Throws:
    
    IllegalArgumentException - if state is #IN_PROGRESS and tranID is null.
  - isFrozen
```
public boolean isFrozen()
```
    Determines whether this candidate pair is frozen or not. Initially, only the candidate pairs with unique foundations are tested. The other candidate pairs are marked "frozen". When the connectivity checks for a candidate pair succeed, the other candidate pairs with the same foundation are unfrozen.
    
    Returns:
    
    true if this candidate pair is frozen and false otherwise.
  - getControllingAgentCandidate
```
public Candidate<?> getControllingAgentCandidate()
```
    Returns the candidate in this pair that belongs to the controlling agent.
    
    Returns:
    
    a reference to the Candidate instance that comes from the controlling agent.
  - getControlledAgentCandidate
```
public Candidate<?> getControlledAgentCandidate()
```
    Returns the candidate in this pair that belongs to the controlled agent.
    
    Returns:
    
    a reference to the Candidate instance that comes from the controlled agent.
  - computePriority
```
protected void computePriority()
```
    A candidate pair priority is computed the following way:
    Let G be the priority for the candidate provided by the controlling agent. Let D be the priority for the candidate provided by the controlled agent. The priority for a pair is computed as:
    pair priority = 2^32*MIN(G,D) + 2*MAX(G,D) + (G>D?1:0)
    This formula ensures a unique priority for each pair. Once the priority is assigned, the agent sorts the candidate pairs in decreasing order of priority. If two pairs have identical priority, the ordering amongst them is arbitrary.
  - getPriority
```
public long getPriority()
```
    Returns the priority of this pair.
    
    Returns:
    
    the priority of this pair.
  - compareTo
```
public int compareTo(CandidatePair candidatePair)
```
    Compares this CandidatePair with the specified object for order. Returns a negative integer, zero, or a positive integer as this CandidatePair's priority is greater than, equal to, or less than the one of the specified object thus insuring that higher priority pairs will come first.
    
    Specified by:
    
    compareTo in interface Comparable<CandidatePair>
    
    Parameters:
    
    candidatePair - the Object to be compared.
    
    Returns:
    
    a negative integer, zero, or a positive integer as this CandidatePair's priority is greater than, equal to, or less than the one of the specified object.
    
    Throws:
    
    ClassCastException - if the specified object's type prevents it from being compared to this Object.
  - equals
```
public boolean equals(Object obj)
```
    Compares this CandidatePair to obj and returns true if pairs have equal local and equal remote candidates and false otherwise.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - the Object that we'd like to compare this pair to.
    
    Returns:
    
    true if pairs have equal local and equal remote candidates and false otherwise.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Returns a String representation of this CandidatePair.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a String representation of the object.
  - toShortString
```
public String toShortString()
```
    Returns a short String representation of this CandidatePair.
    
    Returns:
    
    a short String representation of the object.
  - getParentComponent
```
public Component getParentComponent()
```
    Returns the Component that this pair belongs to.
    
    Returns:
    
    the Component that this pair belongs to.
  - getConnectivityCheckTransaction
```
public TransactionID getConnectivityCheckTransaction()
```
    Returns the TransactionID used in the connectivity check associated with this CandidatePair when it's in the CandidatePairState.IN_PROGRESS or null if it's in any other state.
    
    Returns:
    
    the TransactionID used in the connectivity check associated with this CandidatePair when it's in the CandidatePairState.IN_PROGRESS or null if it's in any other state.
  - setUseCandidateSent
```
public void setUseCandidateSent()
```
    Raises the useCandidateSent flag for this pair.
  - useCandidateSent
```
public boolean useCandidateSent()
```
    Returns true if someone has previously raised this pair's useCandidateSent flag and false otherwise.
    
    Returns:
    
    true if someone has previously raised this pair's useCandidate flag and false otherwise.
  - setUseCandidateReceived
```
public void setUseCandidateReceived()
```
    Raises the useCandidate flag for this pair.
  - useCandidateReceived
```
public boolean useCandidateReceived()
```
    Returns true if someone has previously raised this pair's useCandidate flag and false otherwise.
    
    Returns:
    
    true if someone has previously raised this pair's useCandidate flag and false otherwise.
  - nominate
```
public void nominate()
```
    Sets this pair's nominated flag to true. If a valid candidate pair has its nominated flag set, it means that it may be selected by ICE for sending and receiving media.
  - isNominated
```
public boolean isNominated()
```
    Returns the value of this pair's nominated flag. If a valid candidate pair has its nominated flag set, it means that it may be selected by ICE for sending and receiving media.
    
    Returns:
    
    true if this pair has already been nominated for selection and false otherwise.
  - isValid
```
public boolean isValid()
```
    Returns true if this pair has been confirmed by a connectivity check response and false otherwise.
    
    Returns:
    
    true if this pair has been confirmed by a connectivity check response and false otherwise.
  - validate
```
protected void validate()
```
    Marks this pair as valid. Should only be used internally.
  - getConsentFreshness
```
public long getConsentFreshness()
```
    Gets the time in milliseconds of the latest consent freshness confirmation.
    
    Returns:
    
    the time in milliseconds of the latest consent freshness confirmation
  - setConsentFreshness
```
void setConsentFreshness()
```
    Sets the time in milliseconds of the latest consent freshness confirmation to now.
  - setConsentFreshness
```
void setConsentFreshness(long consentFreshness)
```
    Sets the time in milliseconds of the latest consent freshness confirmation to a specific time.
    
    Parameters:
    
    consentFreshness - the time in milliseconds of the latest consent freshness to be set on this CandidatePair
  - getDatagramSocket
```
@Deprecated
public DatagramSocket getDatagramSocket()
```
    Deprecated.
    
    Returns the UDP DatagramSocket (if any) for this CandidatePair.
    
    Returns:
    
    the UDP DatagramSocket (if any) for this CandidatePair.
  - getSocket
```
@Deprecated
public Socket getSocket()
```
    Deprecated.
    
    Returns the TCP Socket (if any) for this CandidatePair.
    
    Returns:
    
    the TCP Socket (if any) for this CandidatePair.
  - getIceSocketWrapper
```
@Deprecated
public IceSocketWrapper getIceSocketWrapper()
```
    Deprecated.
    
    Returns the IceSocketWrapper for this CandidatePair.
    
    Returns:
    
    the IceSocketWrapper for this CandidatePair.

Class CandidatePair

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONSENT_FRESHNESS_UNKNOWN

MATH_POW_2_32

comparator

localCandidate

remoteCandidate

priority

useCandidate

useCandidateSent

isValid

isNominated

state

connCheckTranID

consentFreshness

Constructor Detail

CandidatePair

Method Detail

getFoundation

getLocalCandidate

setLocalCandidate

getRemoteCandidate

setRemoteCandidate

getState

setStateFailed

setStateFrozen

setStateInProgress

setStateSucceeded

setStateWaiting

setState

isFrozen

getControllingAgentCandidate

getControlledAgentCandidate

computePriority

getPriority

compareTo

equals

hashCode

toString

toShortString

getParentComponent

getConnectivityCheckTransaction

setUseCandidateSent

useCandidateSent

setUseCandidateReceived

useCandidateReceived

nominate

isNominated

isValid

validate

getConsentFreshness

setConsentFreshness

setConsentFreshness

getDatagramSocket

getSocket

getIceSocketWrapper