public class Agent extends Object
As defined in RFC 3264, an agent is the protocol implementation involved in the offer/answer exchange. There are two agents involved in an offer/answer exchange.
Note: An Agent instance should be explicitly prepared for
garbage collection by calling free()
on it if timely freeing of the
associated resources is of importance; otherwise, it will wait for the
garbage collector to call finalize()
on it.
Modifier and Type | Class and Description |
---|---|
private class |
Agent.StunKeepAliveRunner
A class to schedule and perform Stun keep-alive checks
|
Modifier and Type | Field and Description |
---|---|
private static ScheduledExecutorService |
agentTasksScheduler
The ScheduledExecutorService to execute Agent's scheduled tasks
|
private static Logger |
classLogger
|
private ConnectivityCheckClient |
connCheckClient
The entity that will be taking care of outgoing connectivity checks.
|
private ConnectivityCheckServer |
connCheckServer
The entity that will be taking care of incoming connectivity checks.
|
private static int |
DEFAULT_CONSENT_FRESHNESS_INTERVAL
Default value for
StackProperties.CONSENT_FRESHNESS_INTERVAL . |
private static int |
DEFAULT_CONSENT_FRESHNESS_MAX_RETRANSMISSIONS
Default value for
StackProperties.CONSENT_FRESHNESS_MAX_RETRANSMISSIONS . |
private static int |
DEFAULT_CONSENT_FRESHNESS_MAX_WAIT_INTERVAL
Default value for
StackProperties.CONSENT_FRESHNESS_MAX_WAIT_INTERVAL . |
private static int |
DEFAULT_CONSENT_FRESHNESS_ORIGINAL_WAIT_INTERVAL
Default value for
StackProperties.CONSENT_FRESHNESS_ORIGINAL_WAIT_INTERVAL . |
static int |
DEFAULT_MAX_CHECK_LIST_SIZE
The default maximum size for check lists.
|
static int |
DEFAULT_TERMINATION_DELAY
The default number of milliseconds we should wait before moving from
IceProcessingState.COMPLETED into IceProcessingState.TERMINATED . |
private FoundationsRegistry |
foundationsRegistry
We use the FoundationsRegistry to keep track of the foundations
we assign within a session (i.e.
|
private int |
generation
Some protocols, such as XMPP, need to be able to distinguish the separate
ICE sessions that occur as a result of ICE restarts, which is why we need
to keep track of generations.
|
private CandidateHarvesterSet |
harvesters
The set of harvesters (i.e.
|
private boolean |
harvestingStarted
Indicates that harvesting has been started at least once.
|
private HostCandidateHarvester |
hostCandidateHarvester
The candidate harvester that we use to gather candidate on the local
machine.
|
private List<CandidateHarvester> |
hostHarvesters
A list of additional CandidateHarvesters which will be used to
harvest candidates synchronously, and previously to harvesting by
harvesters . |
private boolean |
isControlling
Determines whether this is the controlling agent in a an ICE interaction.
|
private Logger |
logger
|
private Map<String,IceMediaStream> |
mediaStreams
The LinkedHashMap used to store the media streams
This map preserves the insertion order of the media streams.
|
private static PropertyChangeListener[] |
NO_STATE_CHANGE_LISTENERS
The constant which defines an empty array with element type
PropertyChangeListener and represents the fact that there are no
IceProcessingState change listeners added to an Agent
(using
addStateChangeListener(PropertyChangeListener) . |
private DefaultNominator |
nominator
Our internal nominator implementing several nomination strategies.
|
private String |
password
The password that we should use for the ice-pwd attribute.
|
private boolean |
performConsentFreshness
The indicator which determines whether this Agent is to perform
consent freshness.
|
private List<CandidatePair> |
preDiscoveredPairsQueue
The List of remote addresses that we have discovered through
incoming connectivity checks, before actually receiving a session
description from the peer and that may potentially contain peer reflexive
addresses.
|
static String |
PROPERTY_ICE_PROCESSING_STATE
The name of the
PropertyChangeEvent that we use to deliver
events on changes in the state of ICE processing in this agent. |
private boolean |
shutdown
Indicates that ICE will be shutdown.
|
private Object |
startLock
The lock that we use while starting connectivity establishment.
|
private IceProcessingState |
state
Indicates the state of ICE processing in this Agent.
|
private List<PropertyChangeListener> |
stateListeners
Contains
PropertyChangeListener s registered with this Agent and following its changes of state. |
private Object |
stateSyncRoot
Object used to synchronize access to
state . |
private Agent.StunKeepAliveRunner |
stunKeepAliveRunner
An instance to schedule STUN checks for selected pair.
|
private StunStack |
stunStack
The StunStack used by this Agent.
|
private long |
taValue
The value of Ta as specified by the application or -1
if non was specified and we should calculate one ourselves.
|
private ScheduledFuture<?> |
terminationFuture
The scheduled task to terminate this Agent
|
private Object |
terminationFutureSyncRoot
The object used to synchronize access to
terminationFuture . |
private Runnable |
terminationRunnable
Termination task which will be scheduled with timeout
|
private long |
tieBreaker
The tie-breaker number is used in connectivity checks to detect and
repair the case where both agents believe to have the controlling or the
controlled role.
|
private boolean |
trickle
Determines whether this agent should perform trickling.
|
private String |
ufrag
The user fragment that we should use for the ice-ufrag attribute.
|
private Boolean |
useHostHarvester
The flag which specifies whether
hostCandidateHarvester should
be used or not. |
Constructor and Description |
---|
Agent()
Creates an empty Agent with no streams, and no address.
|
Agent(Level loggingLevel)
Creates an empty Agent with no streams, and no address.
|
Agent(Level loggingLevel,
String ufragPrefix)
Creates an empty Agent with no streams, and no address.
|
Agent(String ufragPrefix)
Creates an empty Agent with no streams, and no address.
|
Modifier and Type | Method and Description |
---|---|
void |
addCandidateHarvester(CandidateHarvester harvester)
Adds harvester to the list of harvesters that this agent will
use when gathering Candidates.
|
void |
addStateChangeListener(PropertyChangeListener l)
Adds l to the list of listeners tracking changes of the
IceProcessingState of this Agent |
protected long |
calculateStunConnCheckRTO()
Calculates the value of the retransmission timer to use in STUN
transactions, used in connectivity checks (not to confused with the RTO
for the STUN address harvesting).
|
protected long |
calculateStunHarvestRTO()
Calculates the value of the retransmission timer to use in STUN
transactions, while harvesting addresses (not to confuse with the RTO
for the STUN transactions used in connectivity checks).
|
protected long |
calculateTa()
Calculates the value of the Ta pace timer according to the
number and type of
IceMediaStream s this agent will be using. |
protected void |
checkListStatesUpdated()
After updating check list states as a result of an incoming response
or a timeout event the method goes through all check lists and tries
to assess the state of ICE processing.
|
protected int |
countHostCandidates()
|
protected CandidatePair |
createCandidatePair(LocalCandidate local,
RemoteCandidate remote)
|
Component |
createComponent(IceMediaStream stream,
Transport transport,
int preferredPort,
int minPort,
int maxPort)
Creates a new
Component for the specified stream and
allocates potentially all local candidates that should belong to it. |
Component |
createComponent(IceMediaStream stream,
Transport transport,
int preferredPort,
int minPort,
int maxPort,
KeepAliveStrategy keepAliveStrategy)
Creates a new
Component for the specified stream and
allocates potentially all local candidates that should belong to it. |
Component |
createComponent(IceMediaStream stream,
Transport transport,
int preferredPort,
int minPort,
int maxPort,
KeepAliveStrategy keepAliveStrategy,
boolean useComponentSocket)
Creates a new
Component for the specified stream and
allocates potentially all local candidates that should belong to it. |
IceMediaStream |
createMediaStream(String mediaStreamName)
Creates a new media stream and stores it.
|
private String |
ensureIceAttributeLength(String s,
int min,
int max)
Adds or removes ICE characters (i.e.
|
protected void |
finalize()
Called by the garbage collector when garbage collection determines that
there are no more references to this instance.
|
CandidatePair |
findCandidatePair(String localUFrag,
String remoteUFrag)
Returns the
CandidatePair with the specified remote and local
addresses or null if neither of the CheckList s in this
Agent 's streams contain such a pair. |
CandidatePair |
findCandidatePair(TransportAddress localAddress,
TransportAddress remoteAddress)
Returns the
CandidatePair with the specified remote and local
addresses or null if neither of the CheckList s in this
Agent 's streams contain such a pair. |
LocalCandidate |
findLocalCandidate(TransportAddress localAddress)
Returns the local LocalCandidate with the specified
localAddress if it belongs to any of this
Agent 's
streams or null if it doesn't. |
LocalCandidate |
findLocalCandidate(TransportAddress localAddress,
String ufrag)
Returns the local LocalCandidate with the specified
localAddress if it belongs to any of this
Agent 's
streams or null if it doesn't. |
RemoteCandidate |
findRemoteCandidate(TransportAddress remoteAddress)
Returns the remote Candidate with the specified
remoteAddress if it belongs to any of this
Agent 's
streams or null if it doesn't. |
private void |
fireStateChange(IceProcessingState oldState,
IceProcessingState newState)
Creates a new
PropertyChangeEvent and delivers it to all
currently registered state listeners. |
void |
free()
Prepares this Agent for garbage collection by ending all related
processes and freeing its IceMediaStreams, Components
and Candidates.
|
private void |
gatherCandidates(Component component,
int preferredPort,
int minPort,
int maxPort)
Uses all CandidateHarvesters currently registered with this
Agent to obtain whatever addresses they can discover.
|
String |
generateLocalUserName(RemoteCandidate remoteCandidate,
LocalCandidate localCandidate)
Returns the user name that this Agent should use in connectivity
checks for outgoing Binding Requests in a Google Talk session.
|
String |
generateLocalUserName(String media)
Returns the user name that this Agent should use in connectivity
checks for outgoing Binding Requests.
|
String |
generateRemoteUserName(RemoteCandidate remoteCandidate,
LocalCandidate localCandidate)
Returns the user name that we should expect a peer Agent to use
in connectivity checks for Binding Requests its sending our way in a
Google Talk session.
|
String |
generateRemoteUserName(String media)
Returns the user name that we should expect a peer Agent to use
in connectivity checks for Binding Requests its sending our way.
|
private String |
generateUserName(Candidate<?> candidate1,
Candidate<?> candidate2)
Returns the user name that we should expect a peer Agent to use
in connectivity checks for Binding Requests its sending our way in a
Google Talk session.
|
protected int |
getActiveCheckListCount()
Returns the number of
CheckList s that are currently active. |
FoundationsRegistry |
getFoundationsRegistry()
Returns the
FoundationsRegistry this agent is using to assign
candidate foundations. |
int |
getGeneration()
Returns the current generation of this ICE Agent.
|
int |
getHarvestCount()
Returns the total number of harvests completed by this agent.
|
int |
getHarvestCount(String harvesterName)
Returns the number of harvests that a harvester with a specific class
name has completed so far.
|
CandidateHarvesterSet |
getHarvesters()
Returns the set of harvesters currently in use by this agent.
|
long |
getHarvestingTime(String harvesterName)
Returns the harvesting time (in ms) for the harvester given in parameter.
|
String |
getLocalPassword()
Returns that password that should be advertised in session descriptions
containing ICE data from this agent.
|
String |
getLocalUfrag()
Returns that user name that should be advertised in session descriptions
containing ICE data from this agent.
|
protected Logger |
getLogger() |
Level |
getLoggingLevel()
Gets the logging level for this
Agent and its components. |
boolean |
getPerformConsentFreshness()
Gets the indicator which determines whether this Agent is to
perform consent freshness.
|
LocalCandidate |
getSelectedLocalCandidate(String streamName)
Returns the selected local candidate for this Agent.
|
private CandidatePair |
getSelectedPair(String streamName)
Returns the selected pair for the RTP component for the ICE media stream
with name streamName of this Agent, or null.
|
RemoteCandidate |
getSelectedRemoteCandidate(String streamName)
Returns the selected remote candidate for this Agent.
|
IceProcessingState |
getState()
Returns the state of ICE processing for this Agent.
|
IceMediaStream |
getStream(String name)
Returns the IceMediaStream with the specified name or
null if no such stream has been registered with this
Agent yet.
|
int |
getStreamCount()
Returns the number of IceMediaStreams currently registered with
this agent.
|
List<String> |
getStreamNames()
Returns a List containing the names of all currently registered
media streams.
|
List<IceMediaStream> |
getStreams()
Returns a List containing all IceMediaStreams currently
registered with this agent.
|
(package private) List<IceMediaStream> |
getStreamsWithPendingConnectivityEstablishment()
Gets the IceMediaStreams registered with this Agent for
which connectivity establishment is pending.
|
StunStack |
getStunStack()
Gets the StunStack used by this Agent.
|
long |
getTieBreaker()
Returns this agent's tie-breaker number.
|
long |
getTotalHarvestingTime()
Returns the combined harvesting time for all harvesters in this agent.
|
protected void |
incomingCheckReceived(TransportAddress remoteAddress,
TransportAddress localAddress,
long priority,
String remoteUFrag,
String localUFrag,
boolean useCandidate)
Notifies the implementation that the
ConnectivityCheckServer has
just received a message on localAddress originating at
remoteAddress carrying the specified priority. |
protected void |
initCheckLists()
Creates, initializes and orders the list of candidate pairs that would
be used for the connectivity checks for all components in this stream.
|
boolean |
isControlling()
Determines whether this agent has the controlling role in an ICE
exchange.
|
boolean |
isOver()
Indicates whether this
Agent has finished ICE processing. |
boolean |
isStarted()
Indicates whether this
Agent is currently in the process of
running connectivity checks and establishing connectivity. |
boolean |
isTrickling()
Indicates whether this agent is currently set to trickle candidates
rather than gathering them synchronously while components are being
added.
|
private void |
logCandTypes()
Goes through all streams and components and prints into the logs the type
of local candidates that were selected as well as the server that
were used (if any) to obtain them.
|
void |
nominate(CandidatePair pair)
Raises pair's nomination flag and schedules a triggered check.
|
protected void |
nominationConfirmed(CandidatePair nominatedPair)
Indicates that we have received a response to a request that either
contained the USE-CANDIDATE attribute or was triggered by an
incoming request that did.
|
private void |
pruneNonMatchedStreams()
Free()s and removes from this agent components or entire streams
if they do not contain remote candidates.
|
void |
removeStateChangeListener(PropertyChangeListener l)
Removes l from the list of listeners tracking changes of the
IceProcessingState of this Agent |
void |
removeStream(IceMediaStream stream)
Removes stream and all its child Components and
Candidates from the this agent and releases all resources that
they had allocated (like sockets for example)
|
private void |
scheduleStunKeepAlive()
Schedules repeated background task which sends STUN keep-alives
once this Agent is COMPLETED.
|
private void |
scheduleTermination()
Initializes and starts the
terminationFuture |
void |
setControlling(boolean isControlling)
Specifies whether this agent has the controlling role in an ICE exchange.
|
void |
setGeneration(int generation)
Specifies the current generation of this ICE Agent.
|
void |
setLoggingLevel(Level level)
Sets the logging level for this
Agent and its components. |
void |
setNominationStrategy(NominationStrategy strategy)
Specifies the
NominationStrategy that we should use in order to
decide if and when we should nominate valid pairs. |
void |
setPerformConsentFreshness(boolean performConsentFreshness)
Sets the indicator which determines whether this Agent is to
perform consent freshness.
|
private boolean |
setState(IceProcessingState newState)
Sets the
IceProcessingState of this Agent to
newState and triggers the corresponding change event. |
void |
setStunStack(StunStack stunStack)
Sets the StunStack used by this Agent.
|
void |
setTa(long taValue)
Lets the application specify a custom value for the Ta timer
so that we don't calculate one.
|
void |
setTieBreaker(long tieBreakerInput)
Sets the tie breaker value.
|
void |
setTrickling(boolean trickle)
Determines whether this agent will trickle candidates rather than
gather them synchronously while components are being added.
|
void |
setUseHostHarvester(boolean useHostHarvester)
Sets the flag which indicates whether the dynamic host harvester will
be used or not by this Agent.
|
void |
startCandidateTrickle(TrickleCallback trickleCallback)
Starts an asynchronous(?) harvest across all components and reports newly
discovered candidates to trickleCallback.
|
void |
startConnectivityEstablishment()
Initializes all stream check lists and begins the checks.
|
private void |
terminate(IceProcessingState terminationState)
Terminates this Agent by stopping the handling of connectivity
checks and setting a specific termination state on it.
|
String |
toString()
Returns a String representation of this agent.
|
private void |
triggerCheck(CandidatePair triggerPair)
Either queues a triggered check for triggeredPair or, in case
there's already a pair with the specified remote and local addresses,
puts it in the queue instead.
|
boolean |
useHostHarvester()
Checks whether the dynamic host harvester should be used or not.
|
protected void |
validatePair(CandidatePair validPair)
Adds pair to that list of valid candidates for its parent
stream.
|
private static final int DEFAULT_CONSENT_FRESHNESS_INTERVAL
StackProperties.CONSENT_FRESHNESS_INTERVAL
.private static final int DEFAULT_CONSENT_FRESHNESS_MAX_RETRANSMISSIONS
StackProperties.CONSENT_FRESHNESS_MAX_RETRANSMISSIONS
.private static final int DEFAULT_CONSENT_FRESHNESS_MAX_WAIT_INTERVAL
StackProperties.CONSENT_FRESHNESS_MAX_WAIT_INTERVAL
.private static final int DEFAULT_CONSENT_FRESHNESS_ORIGINAL_WAIT_INTERVAL
StackProperties.CONSENT_FRESHNESS_ORIGINAL_WAIT_INTERVAL
.public static final int DEFAULT_MAX_CHECK_LIST_SIZE
public static final int DEFAULT_TERMINATION_DELAY
IceProcessingState.COMPLETED
into IceProcessingState.TERMINATED
.private static final PropertyChangeListener[] NO_STATE_CHANGE_LISTENERS
addStateChangeListener(PropertyChangeListener)
.private static final Logger classLogger
public static final String PROPERTY_ICE_PROCESSING_STATE
PropertyChangeEvent
that we use to deliver
events on changes in the state of ICE processing in this agent.private static final ScheduledExecutorService agentTasksScheduler
private final Runnable terminationRunnable
private final Agent.StunKeepAliveRunner stunKeepAliveRunner
private final Map<String,IceMediaStream> mediaStreams
private final HostCandidateHarvester hostCandidateHarvester
private final List<CandidateHarvester> hostHarvesters
harvesters
.private final CandidateHarvesterSet harvesters
private final FoundationsRegistry foundationsRegistry
private final DefaultNominator nominator
private long taValue
private final List<CandidatePair> preDiscoveredPairsQueue
private final Object startLock
private final String ufrag
private final String password
private long tieBreaker
private boolean isControlling
private final ConnectivityCheckClient connCheckClient
private final ConnectivityCheckServer connCheckServer
private IceProcessingState state
private final List<PropertyChangeListener> stateListeners
PropertyChangeListener
s registered with this Agent
and following its changes of state.private StunStack stunStack
private ScheduledFuture<?> terminationFuture
private final Object terminationFutureSyncRoot
terminationFuture
.private int generation
private boolean trickle
private boolean shutdown
private boolean harvestingStarted
private boolean performConsentFreshness
private Boolean useHostHarvester
hostCandidateHarvester
should
be used or not.private final Logger logger
public Agent()
public Agent(String ufragPrefix)
ufragPrefix
- an optional prefix to the generated local ICE username
fragment.public Agent(Level loggingLevel)
loggingLevel
- the logging level to be used by the agent and all of
its components.public void setTieBreaker(long tieBreakerInput)
tieBreakerInput
- the value to set.public IceMediaStream createMediaStream(String mediaStreamName)
mediaStreamName
- the name of the media streampublic Component createComponent(IceMediaStream stream, Transport transport, int preferredPort, int minPort, int maxPort) throws IllegalArgumentException, IOException, BindException
Component
for the specified stream and
allocates potentially all local candidates that should belong to it.stream
- the IceMediaStream
that the new Component
should belong to.transport
- the transport protocol used by the componentpreferredPort
- the port number that should be tried first when
binding local Candidate sockets for this Component.minPort
- the port number where we should first try to bind before
moving to the next one (i.e. minPort + 1)maxPort
- the maximum port number where we should try binding
before giving up and throwing an exception.Component
and with a list containing
all and only local candidates.IllegalArgumentException
- if either minPort or
maxPort is not a valid port number or if minPort >
maxPort, or if transport is not currently supported.IOException
- if an error occurs while the underlying resolver lib
is using sockets.BindException
- if we couldn't find a free port between
minPort and maxPort before reaching the maximum allowed
number of retries.public Component createComponent(IceMediaStream stream, Transport transport, int preferredPort, int minPort, int maxPort, KeepAliveStrategy keepAliveStrategy) throws IllegalArgumentException, IOException, BindException
Component
for the specified stream and
allocates potentially all local candidates that should belong to it.stream
- the IceMediaStream
that the new Component
should belong to.transport
- the transport protocol used by the componentpreferredPort
- the port number that should be tried first when
binding local Candidate sockets for this Component.minPort
- the port number where we should first try to bind before
moving to the next one (i.e. minPort + 1)maxPort
- the maximum port number where we should try binding
before giving up and throwing an exception.keepAliveStrategy
- the keep-alive strategy, which dictates which
candidates pairs are going to be kept alive.Component
and with a list containing
all and only local candidates.IllegalArgumentException
- if either minPort or
maxPort is not a valid port number or if minPort >
maxPort, or if transport is not currently supported.IOException
- if an error occurs while the underlying resolver lib
is using sockets.BindException
- if we couldn't find a free port between
minPort and maxPort before reaching the maximum allowed
number of retries.public Component createComponent(IceMediaStream stream, Transport transport, int preferredPort, int minPort, int maxPort, KeepAliveStrategy keepAliveStrategy, boolean useComponentSocket) throws IllegalArgumentException, IOException, BindException
Component
for the specified stream and
allocates potentially all local candidates that should belong to it.stream
- the IceMediaStream
that the new Component
should belong to.transport
- the transport protocol used by the componentpreferredPort
- the port number that should be tried first when
binding local Candidate sockets for this Component.minPort
- the port number where we should first try to bind before
moving to the next one (i.e. minPort + 1)maxPort
- the maximum port number where we should try binding
before giving up and throwing an exception.keepAliveStrategy
- the keep-alive strategy, which dictates which
candidates pairs are going to be kept alive.useComponentSocket
- whether to use the component socket mode (in
which case the socket is available through the Component
directly),
or not (in which case the socket is available through the selected
CandidatePair
).Component
and with a list containing
all and only local candidates.IllegalArgumentException
- if either minPort or
maxPort is not a valid port number or if minPort >
maxPort, or if transport is not currently supported.IOException
- if an error occurs while the underlying resolver lib
is using sockets.BindException
- if we couldn't find a free port between
minPort and maxPort before reaching the maximum allowed
number of retries.protected CandidatePair createCandidatePair(LocalCandidate local, RemoteCandidate remote)
CandidatePair
instance from a
LocalCandidate
and a RemoteCandidate
. The method
represents a CandidatePair
factory and is preferable to
explicitly calling the CandidatePair
constructor because it
allows this Agent
to easily track the initialization of its
CandidatePair
s.local
- the LocalCandidate
to initialize the new instance
withremote
- the RemoteCandidate
to initialize the new instance
withCandidatePair
instance initializes with
local
and remote
private void gatherCandidates(Component component, int preferredPort, int minPort, int maxPort) throws IllegalArgumentException, IOException
Not that the method would only use existing harvesters so make sure you've registered all harvesters that you would want to use before calling it.
component
- the Component that we'd like to gather
candidates for.preferredPort
- the port number that should be tried first when
binding local Candidate sockets for this Component.minPort
- the port number where we should first try to bind before
moving to the next one (i.e. minPort + 1)maxPort
- the maximum port number where we should try binding
before giving up and throwing an exception.IllegalArgumentException
- if either minPort or
maxPort is not a valid port number or if minPort >
maxPort.IOException
- if an error occurs while the underlying resolver lib
is gathering candidates and we end up without even a single one.public void startCandidateTrickle(TrickleCallback trickleCallback) throws IllegalStateException
trickleCallback
- the callback that will be notified for all newly
discovered candidates.IllegalStateException
- if we try calling this method without being
in a trickling state.public void startConnectivityEstablishment()
private void pruneNonMatchedStreams()
public boolean isStarted()
Agent
is currently in the process of
running connectivity checks and establishing connectivity. Connectivity
establishment is considered to have started after both Agent
s
have exchanged their media descriptions. Determining whether the actual
process has started is important, for example, when determining whether
a remote address we've just discovered is peer reflexive or not.
If ICE has started and we don't know about the address then we should
add it to the list of candidates. Otherwise we should hold to it until
it does and check later.
Note that an Agent
would be ready to and will send responses to
connectivity checks as soon as it streams get created, which is well
before we actually start the checks.
public boolean isOver()
Agent
has finished ICE processing.IceProcessingState.FAILED
, IceProcessingState.COMPLETED
or
IceProcessingState.TERMINATED
and false otherwise.public IceProcessingState getState()
public void addStateChangeListener(PropertyChangeListener l)
IceProcessingState
of this Agentl
- the listener to register.public void removeStateChangeListener(PropertyChangeListener l)
IceProcessingState
of this Agentl
- the listener to remove.private void fireStateChange(IceProcessingState oldState, IceProcessingState newState)
PropertyChangeEvent
and delivers it to all
currently registered state listeners.oldState
- the IceProcessingState
we had before the changenewState
- the IceProcessingState
we had after the changeprivate boolean setState(IceProcessingState newState)
IceProcessingState
of this Agent to
newState and triggers the corresponding change event.newState
- the new state of ICE processing for this Agent.protected void initCheckLists()
public void addCandidateHarvester(CandidateHarvester harvester)
harvester
- a CandidateHarvester that this agent should use
when gathering candidates.public CandidateHarvesterSet getHarvesters()
public String getLocalUfrag()
public String getLocalPassword()
public String generateLocalUserName(String media)
media
- media name that we want to generate local username for.public String generateRemoteUserName(String media)
media
- media name that we want to generate local username for.public String generateLocalUserName(RemoteCandidate remoteCandidate, LocalCandidate localCandidate)
remoteCandidate
- remote candidatelocalCandidate
- local candidatepublic String generateRemoteUserName(RemoteCandidate remoteCandidate, LocalCandidate localCandidate)
remoteCandidate
- remote candidatelocalCandidate
- local candidateprivate String generateUserName(Candidate<?> candidate1, Candidate<?> candidate2)
candidate1
- The first candidate of a candidatePair.candidate2
- The second candidate of a candidatePair.public final FoundationsRegistry getFoundationsRegistry()
FoundationsRegistry
this agent is using to assign
candidate foundations. We use the FoundationsRegistry to keep
track of the foundations we assign within a session (i.e. the entire life
time of an Agent)FoundationsRegistry
of this agentpublic IceMediaStream getStream(String name)
name
- the name of the stream that we'd like to obtain a reference
to.public List<String> getStreamNames()
public List<IceMediaStream> getStreams()
public int getStreamCount()
List<IceMediaStream> getStreamsWithPendingConnectivityEstablishment()
public StunStack getStunStack()
public void setStunStack(StunStack stunStack)
stunStack
- the stunStack to be used by this Agent.protected int getActiveCheckListCount()
CheckList
s that are currently active.CheckList
s that are currently active.public String toString()
public long getTieBreaker()
public void setControlling(boolean isControlling)
isControlling
- true if this is to be the controlling
Agent and false otherwise.public void removeStream(IceMediaStream stream)
stream
- the Component we'd like to remove and free.public boolean isControlling()
public LocalCandidate findLocalCandidate(TransportAddress localAddress)
Agent
's
streams or null if it doesn't.localAddress
- the TransportAddress
we are looking for.Agent
's
streams or null if it doesn't.public LocalCandidate findLocalCandidate(TransportAddress localAddress, String ufrag)
Agent
's
streams or null if it doesn't.localAddress
- the TransportAddress
we are looking for.ufrag
- local ufragAgent
's
streams or null if it doesn't.public RemoteCandidate findRemoteCandidate(TransportAddress remoteAddress)
Agent
's
streams or null if it doesn't.remoteAddress
- the TransportAddress
we are looking for.Agent
's
streams or null if it doesn't.public CandidatePair findCandidatePair(TransportAddress localAddress, TransportAddress remoteAddress)
CandidatePair
with the specified remote and local
addresses or null if neither of the CheckList
s in this
Agent
's streams contain such a pair.localAddress
- the local TransportAddress
of the pair we
are looking for.remoteAddress
- the remote TransportAddress
of the pair we
are looking for.CandidatePair
with the specified remote and local
addresses or null if neither of the CheckList
s in this
Agent
's streams contain such a pair.public CandidatePair findCandidatePair(String localUFrag, String remoteUFrag)
CandidatePair
with the specified remote and local
addresses or null if neither of the CheckList
s in this
Agent
's streams contain such a pair.localUFrag
- local user fragmentremoteUFrag
- remote user fragmentCandidatePair
with the specified remote and local
addresses or null if neither of the CheckList
s in this
Agent
's streams contain such a pair.protected void incomingCheckReceived(TransportAddress remoteAddress, TransportAddress localAddress, long priority, String remoteUFrag, String localUFrag, boolean useCandidate)
ConnectivityCheckServer
has
just received a message on localAddress originating at
remoteAddress carrying the specified priority. This
will cause us to schedule a triggered check for the corresponding
remote candidate and potentially to the discovery of a PEER-REFLEXIVE
candidate.remoteAddress
- the address that we've just seen, and that is
potentially a peer-reflexive address.localAddress
- the address that we were contacted on.priority
- the priority that the remote party assigned toremoteUFrag
- the user fragment that we should be using when and if
we decide to send a check to remoteAddress.localUFrag
- local user fragmentuseCandidate
- indicates whether the incoming check
Request
contained the USE-CANDIDATE ICE
attribute.private void triggerCheck(CandidatePair triggerPair)
triggerPair
- the pair containing the local and remote candidate
that we'd need to trigger a check for.protected void validatePair(CandidatePair validPair)
validPair
- the CandidatePair
we'd like to validate.public void nominate(CandidatePair pair) throws IllegalStateException
pair
- the CandidatePair
that we'd like to nominate and that
we'd like to schedule a triggered check for.IllegalStateException
- if this Agent is not a controlling
agent and can therefore not nominate pairs.setNominationStrategy(NominationStrategy)
public void setNominationStrategy(NominationStrategy strategy)
NominationStrategy
that we should use in order to
decide if and when we should nominate valid pairs.strategy
- the strategy that we'd like to use for nominating
valid CandidatePair
s.protected void nominationConfirmed(CandidatePair nominatedPair)
nominatedPair
- the CandidatePair
whose nomination has
just been confirmed.protected void checkListStatesUpdated()
private void logCandTypes()
protected int countHostCandidates()
public void setTa(long taValue)
taValue
- the value of the Ta timer that the application
would like us to use rather than calculate one.protected long calculateTa()
IceMediaStream
s this agent will be using.
During the gathering phase of ICE (Section 4.1.1) and while ICE is performing connectivity checks (Section 7), an agent sends STUN and TURN transactions. These transactions are paced at a rate of one every Ta milliseconds.
As per RFC 5245, the value of Ta should be configurable so if someone has set a value of their own, we return that value rather than calculating a new one.
IceMediaStream
s this agent will be using or
a pre-configured value if the application has set one.protected long calculateStunHarvestRTO()
protected long calculateStunConnCheckRTO()
private void scheduleTermination()
terminationFuture
private void scheduleStunKeepAlive()
private void terminate(IceProcessingState terminationState)
terminationState
- the state that we'd like processing to terminate
with i.e. either IceProcessingState.TERMINATED
or
IceProcessingState.FAILED
private String ensureIceAttributeLength(String s, int min, int max)
s
- the String to add or remove characters to or from in
case its length is less than min or greater than maxmin
- the minimum length in (ICE) characters of the returned
Stringmax
- the maximum length in (ICE) characters of the returned
StringIllegalArgumentException
- if min is negative or
max is less than minNullPointerException
- if s is equal to nullprotected void finalize() throws Throwable
free()
on
this instance.public void free()
public int getGeneration()
public void setGeneration(int generation)
generation
- the current generation of this ICE Agentprivate CandidatePair getSelectedPair(String streamName)
streamName
- The stream name.public LocalCandidate getSelectedLocalCandidate(String streamName)
streamName
- The stream name (AUDIO, VIDEO);public RemoteCandidate getSelectedRemoteCandidate(String streamName)
streamName
- The stream name (AUDIO, VIDEO);public boolean isTrickling()
public void setTrickling(boolean trickle)
trickle
- false if this agent is configured to perform all
harvesting when components are being added and false otherwise.public long getHarvestingTime(String harvesterName)
harvesterName
- The class name if the harvester.public int getHarvestCount(String harvesterName)
harvesterName
- the class name of the harvester for which the
number of completed harvests is to be returnedpublic long getTotalHarvestingTime()
public int getHarvestCount()
public boolean getPerformConsentFreshness()
public void setPerformConsentFreshness(boolean performConsentFreshness)
performConsentFreshness
- true if this Agent is to
perform consent freshness; otherwise, falsepublic boolean useHostHarvester()
public void setUseHostHarvester(boolean useHostHarvester)
useHostHarvester
- the value to set.public void setLoggingLevel(Level level)
Agent
and its components.level
- the level to set.public Level getLoggingLevel()
Agent
and its components.Copyright © 2018. All rights reserved.