Package org.jenkinsci.remoting.engine
Class JnlpConnectionState
- java.lang.Object
-
- org.jenkinsci.remoting.engine.JnlpConnectionState
-
- Direct Known Subclasses:
Jnlp4ConnectionState
@NotThreadSafe public class JnlpConnectionState extends Object
Represents the state of a connection event. This object should not be retained by theJnlpConnectionStateListener
- Since:
- 3.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
JnlpConnectionState.ListenerState
Marker base class for all stashed state data.
-
Field Summary
Fields Modifier and Type Field Description static String
CLIENT_NAME_KEY
The property name for the client name key.static String
COOKIE_KEY
The property name for the cookie name key.static String
SECRET_KEY
The property name for the secret key.
-
Constructor Summary
Constructors Constructor Description JnlpConnectionState(Socket socket, List<? extends JnlpConnectionStateListener> listeners)
Constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
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
fireAfterDisconnect()
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
fireBeforeProperties()
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.Channel
getChannel()
Gets the connection'sChannel
.ChannelBuilder
getChannelBuilder()
Gets theChannelBuilder
that will be used to create the connection'sChannel
.IOException
getCloseCause()
Gets the reason for the channel being closed if available.Map<String,String>
getProperties()
Gets the connection properties.String
getProperty(String name)
Gets the named connection property.String
getRemoteEndpointDescription()
Description of the remote endpoint to whichgetSocket()
is connected, if using an actual socket and it is actually connected.Socket
getSocket()
Gets the socket that the connection is on.<S extends JnlpConnectionState.ListenerState>
SgetStash(Class<S> clazz)
Retrieves 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 Detail
-
SECRET_KEY
public static final String SECRET_KEY
The property name for the secret key.- See Also:
- Constant Field Values
-
CLIENT_NAME_KEY
public static final String CLIENT_NAME_KEY
The property name for the client name key.- See Also:
- Constant Field Values
-
COOKIE_KEY
public static final String COOKIE_KEY
The property name for the cookie name key.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
JnlpConnectionState
public JnlpConnectionState(@Nullable Socket socket, List<? extends JnlpConnectionStateListener> listeners)
Constructor.- Parameters:
socket
- theSocket
.listeners
- theJnlpConnectionStateListener
instances.
-
-
Method Detail
-
getSocket
@NonNull public Socket 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
@NonNull public String 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
public void setRemoteEndpointDescription(@NonNull String description)
Set a specific value forgetRemoteEndpointDescription()
.
-
getProperties
public Map<String,String> getProperties()
Gets the connection properties.- Returns:
- the connection properties.
- Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
-
getProperty
public String getProperty(String name)
Gets the named connection property.- Parameters:
name
- the property name.- Returns:
- the connection property.
- Throws:
IllegalStateException
- if invoked beforeJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
-
getChannelBuilder
public ChannelBuilder getChannelBuilder()
Gets theChannelBuilder
that will be used to create the connection'sChannel
.- Returns:
- the
ChannelBuilder
- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeChannel(JnlpConnectionState)
-
getChannel
public Channel 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
@CheckForNull public IOException 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
public 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.- Throws:
IllegalStateException
- if invoked outside ofJnlpConnectionStateListener.beforeProperties(JnlpConnectionState)
orJnlpConnectionStateListener.afterProperties(JnlpConnectionState)
.
-
getStash
@CheckForNull public <S extends JnlpConnectionState.ListenerState> S getStash(Class<S> clazz)
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(ListenerState)
-
setStash
public <S extends JnlpConnectionState.ListenerState> void setStash(@CheckForNull S stash)
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:
getStash(Class)
-
fireBeforeProperties
public void fireBeforeProperties() throws ConnectionRefusalException
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 ConnectionRefusalException
Advances the connection state to indicate that the property exchange has completed.- Throws:
ConnectionRefusalException
- if the connection has been refused.
-
fireBeforeChannel
public void fireBeforeChannel(ChannelBuilder builder)
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
public void fireAfterChannel(Channel channel)
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
public void fireChannelClosed(@CheckForNull IOException cause)
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.
-
-