Package org.jenkinsci.remoting.engine
Class JnlpConnectionState
java.lang.Object
org.jenkinsci.remoting.engine.JnlpConnectionState
- Direct Known Subclasses:
Jnlp4ConnectionState
Represents the state of a connection event. This object should not be retained by the
JnlpConnectionStateListener
- Since:
- 3.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Marker base class for all stashed state data. -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionJnlpConnectionState
(Socket socket, List<? extends JnlpConnectionStateListener> listeners) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionvoid
approve()
Signals that the currentJnlpConnectionStateListener
is declaring ownership of this event, approving the connection and all otherJnlpConnectionStateListener
instances will now be ignored.void
fireAfterChannel
(Channel channel) Advances the connection state to indicate that the channel has been created.void
Advances the connection state to indicate that the socket has been closed.void
fireAfterProperties
(Map<String, String> properties) Advances the connection state to indicate that the property exchange has completed.void
fireBeforeChannel
(ChannelBuilder builder) Advances the connection state to indicate that the channel is about to be created.void
Advances the connection state to indicate that a connection has been "secured" and the property exchange is about to take place.void
fireChannelClosed
(IOException cause) Advances the connection state to indicate that the channel has been closed.Gets the connection'sChannel
.Gets theChannelBuilder
that will be used to create the connection'sChannel
.Gets the reason for the channel being closed if available.Gets the connection properties.getProperty
(String name) Gets the named connection property.Description of the remote endpoint to whichgetSocket()
is connected, if using an actual socket and it is actually connected.Gets the socket that the connection is on.<S extends JnlpConnectionState.ListenerState>
SRetrieves the previously stashed state.void
ignore()
Signals that the currentJnlpConnectionStateListener
is not interested in this event any more.void
reject
(ConnectionRefusalException reason) Signals that the currentJnlpConnectionStateListener
is declaring ownership of this event, rejecting the connection and all otherJnlpConnectionStateListener
instances will now be ignored.void
setRemoteEndpointDescription
(String description) Set a specific value forgetRemoteEndpointDescription()
.<S extends JnlpConnectionState.ListenerState>
voidsetStash
(S stash) Stores some listener specific state for later retrieval.
-
Field Details
-
SECRET_KEY
The property name for the secret key.- See Also:
-
CLIENT_NAME_KEY
The property name for the client name key.- See Also:
-
COOKIE_KEY
The property name for the cookie name key.- See Also:
-
-
Constructor Details
-
JnlpConnectionState
public JnlpConnectionState(@Nullable Socket socket, List<? extends JnlpConnectionStateListener> listeners) Constructor.- Parameters:
socket
- theSocket
.listeners
- theJnlpConnectionStateListener
instances.
-
-
Method Details
-
getSocket
Gets the socket that the connection is on.This should be considered deprecated except in situations where you know an actual socket is involved. Use
getRemoteEndpointDescription()
for logging purposes.- Returns:
- an actual socket, or just a stub
-
getRemoteEndpointDescription
Description of the remote endpoint to whichgetSocket()
is connected, if using an actual socket and it is actually connected. Or may be some other text identifying a remote client.- Returns:
- some text suitable for debug logs
-
setRemoteEndpointDescription
Set a specific value forgetRemoteEndpointDescription()
. -
getProperties
Gets the connection properties.- Returns:
- the connection properties.
- Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
-
getProperty
Gets the named connection property.- Parameters:
name
- the property name.- Returns:
- the connection property.
- Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
-
getChannelBuilder
Gets theChannelBuilder
that will be used to create the connection'sChannel
.- Returns:
- the
ChannelBuilder
- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeChannel(JnlpConnectionState)
-
getChannel
Gets the connection'sChannel
.- Returns:
- the
Channel
(may be closed already), may benull
inJnlpConnectionStateListener.afterDisconnect(JnlpConnectionState)
if the socket was closed by the client. - Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.afterChannel(JnlpConnectionState)
-
getCloseCause
Gets the reason for the channel being closed if available.- Returns:
- the reason or
null
if termination was normal. - Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.channelClosed(JnlpConnectionState)
-
ignore
public void ignore()Signals that the currentJnlpConnectionStateListener
is not interested in this event any more. If allJnlpConnectionStateListener
implementations ignore the event then the connection will be rejected.- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeProperties(JnlpConnectionState)
orJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
.
-
approve
public void approve()Signals that the currentJnlpConnectionStateListener
is declaring ownership of this event, approving the connection and all otherJnlpConnectionStateListener
instances will now be ignored. This method must be called by at least oneJnlpConnectionStateListener
or the connection will be rejected.- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeProperties(JnlpConnectionState)
orJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
.
-
reject
Signals that the currentJnlpConnectionStateListener
is declaring ownership of this event, rejecting the connection and all otherJnlpConnectionStateListener
instances will now be ignored.- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeProperties(JnlpConnectionState)
orJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
.
-
getStash
Retrieves the previously stashed state.- Type Parameters:
S
- the expected class of the stashed state.- Parameters:
clazz
- the expected class of the stashed state.- Returns:
- the stashed state.
- Throws:
IllegalStateException
- if invoked beforeapprove()
- See Also:
-
setStash
Stores some listener specific state for later retrieval.- Type Parameters:
S
- the expected class of the stashed state.- Parameters:
stash
- the state to stash.- Throws:
IllegalStateException
- if invoked beforeapprove()
- See Also:
-
fireBeforeProperties
Advances the connection state to indicate that a connection has been "secured" and the property exchange is about to take place.- Throws:
ConnectionRefusalException
- if the connection has been refused.
-
fireAfterProperties
public void fireAfterProperties(@NonNull Map<String, String> properties) throws ConnectionRefusalExceptionAdvances the connection state to indicate that the property exchange has completed.- Throws:
ConnectionRefusalException
- if the connection has been refused.
-
fireBeforeChannel
Advances the connection state to indicate that the channel is about to be created.- Parameters:
builder
- theChannelBuilder
that will be used to create the channel.
-
fireAfterChannel
Advances the connection state to indicate that the channel has been created.- Parameters:
channel
- theChannel
(may be closed already but should not unless there is a serious race with the remote).
-
fireChannelClosed
Advances the connection state to indicate that the channel has been closed.- Parameters:
cause
- the reason why the channel was closed ornull
if normally closed
-
fireAfterDisconnect
public void fireAfterDisconnect()Advances the connection state to indicate that the socket has been closed.
-