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 the JnlpConnectionStateListener

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 final String	CLIENT_NAME_KEY	The property name for the client name key.
static final String	COOKIE_KEY	The property name for the cookie name key.
static final 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

Modifier and Type	Method	Description
void	approve()	Signals that the current JnlpConnectionStateListener is declaring ownership of this event, approving the connection and all other JnlpConnectionStateListener 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's Channel.
ChannelBuilder	getChannelBuilder()	Gets the ChannelBuilder that will be used to create the connection's Channel.
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 which getSocket() 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> S	getStash(Class<S> clazz)	Retrieves the previously stashed state.
void	ignore()	Signals that the current JnlpConnectionStateListener is not interested in this event any more.
void	reject(ConnectionRefusalException reason)	Signals that the current JnlpConnectionStateListener is declaring ownership of this event, rejecting the connection and all other JnlpConnectionStateListener instances will now be ignored.
void	setRemoteEndpointDescription(String description)	Set a specific value for getRemoteEndpointDescription().
<S extends JnlpConnectionState.ListenerState> void	setStash(S stash)	Stores some listener specific state for later retrieval.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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 Details

JnlpConnectionState

public JnlpConnectionState(@Nullable
 Socket socket,
 List<? extends JnlpConnectionStateListener> listeners)

Constructor.

Parameters:

socket - the Socket.

listeners - the JnlpConnectionStateListener instances.

Method Details

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 which getSocket() 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 for getRemoteEndpointDescription().

getProperties

public Map<String,String> getProperties()

Gets the connection properties.

Returns:

the connection properties.

Throws:

IllegalStateException - if invoked before JnlpConnectionStateListener.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 before JnlpConnectionStateListener.afterProperties(JnlpConnectionState)

getChannelBuilder

public ChannelBuilder getChannelBuilder()

Gets the ChannelBuilder that will be used to create the connection's Channel.

Returns:

the ChannelBuilder

Throws:

IllegalStateException - if invoked outside of JnlpConnectionStateListener.beforeChannel(JnlpConnectionState)

getChannel

public Channel getChannel()

Gets the connection's Channel.

Returns:

the Channel (may be closed already), may be null in JnlpConnectionStateListener.afterDisconnect(JnlpConnectionState) if the socket was closed by the client.

Throws:

IllegalStateException - if invoked before JnlpConnectionStateListener.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 before JnlpConnectionStateListener.channelClosed(JnlpConnectionState)

ignore

public void ignore()

Signals that the current JnlpConnectionStateListener is not interested in this event any more. If all JnlpConnectionStateListener implementations ignore the event then the connection will be rejected.

Throws:

IllegalStateException - if invoked outside of JnlpConnectionStateListener.beforeProperties(JnlpConnectionState) or JnlpConnectionStateListener.afterProperties(JnlpConnectionState).

approve

public void approve()

Signals that the current JnlpConnectionStateListener is declaring ownership of this event, approving the connection and all other JnlpConnectionStateListener instances will now be ignored. This method must be called by at least one JnlpConnectionStateListener or the connection will be rejected.

Throws:

IllegalStateException - if invoked outside of JnlpConnectionStateListener.beforeProperties(JnlpConnectionState) or JnlpConnectionStateListener.afterProperties(JnlpConnectionState).

reject

public void reject(ConnectionRefusalException reason)

Signals that the current JnlpConnectionStateListener is declaring ownership of this event, rejecting the connection and all other JnlpConnectionStateListener instances will now be ignored.

Throws:

IllegalStateException - if invoked outside of JnlpConnectionStateListener.beforeProperties(JnlpConnectionState) or JnlpConnectionStateListener.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 before approve()

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 before approve()

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 - the ChannelBuilder 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 - the Channel (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 or null if normally closed

fireAfterDisconnect

public void fireAfterDisconnect()

Advances the connection state to indicate that the socket has been closed.