Package hudson.remoting

Class Engine

java.lang.Object

java.lang.Thread

hudson.remoting.Engine

All Implemented Interfaces:

Runnable

@NotThreadSafe
public class Engine
extends Thread

Agent engine that proactively connects to Jenkins controller.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field	Description
boolean	failIfWorkDirIsMissing	Fail the initialization if the workDir or internalDir are missing.
String	internalDir	Specifies a directory within workDir, which stores all the remoting-internal files.
final EngineListener	listener	Deprecated. Use events.
static final String	REMOTING_MINIMUM_VERSION_HEADER	HTTP header sent by Jenkins to indicate the earliest version of Remoting it is prepared to accept connections from.
static final String	WEBSOCKET_COOKIE_HEADER	The header name to be used for the connection cookie when using websockets.
Path	workDir	Specifies a default working directory of the remoting instance.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor	Description
Engine(EngineListener listener, List<URL> hudsonUrls, String secretKey, String agentName)
Engine(EngineListener listener, List<URL> hudsonUrls, String secretKey, String agentName, String directConnection, String instanceIdentity, Set<String> protocols)

Method Summary

Modifier and Type	Method	Description
void	addCandidateCertificate(X509Certificate certificate)
void	addListener(EngineListener el)
static Engine	current()	When invoked from within remoted Callable (that is, from the thread that carries out the remote requests), this method returns the Engine in which the remote operations run.
String	getAgentName()	Get the agent name associated with this Engine instance.
URL	getHudsonUrl()	Provides Jenkins URL if available.
String	getProtocolName()	Get the name of the communication protocol used in this Engine instance.
boolean	isDisableHttpsCertValidation()	Determines if JNLPAgentEndpointResolver will not perform certificate validation in the HTTPs mode.
boolean	isKeepAlive()	Returns true if and only if the socket to the controller will have Socket.setKeepAlive(boolean) set.
void	removeListener(EngineListener el)
void	run()
void	setAgentLog(Path agentLog)	Sets the destination for agent logs.
void	setCandidateCertificates(List<X509Certificate> candidateCertificates)
void	setCredentials(String creds)
void	setDisableHttpsCertValidation(boolean disableHttpsCertValidation)	Sets if JNLPAgentEndpointResolver will not perform certificate validation in the HTTPs mode.
void	setFailIfWorkDirIsMissing(boolean failIfWorkDirIsMissing)	Sets up behavior if the workDir or internalDir are missing during the startup.
void	setInternalDir(String internalDir)	Specifies name of the internal data directory within workDir.
void	setJarCache(JarCache jarCache)	Configures custom JAR Cache location.
void	setKeepAlive(boolean keepAlive)	Sets the Socket.setKeepAlive(boolean) to use for the connection to the controller.
void	setLoggingConfigFile(Path filePath)	Sets path to the property file with JUL settings.
void	setNoReconnect(boolean noReconnect)
void	setNoReconnectAfter(Duration noReconnectAfter)
void	setProxyCredentials(String proxyCredentials)
void	setTunnel(String tunnel)	If set, connect to the specified host and port instead of connecting directly to Jenkins.
void	setWebSocket(boolean webSocket)
void	setWebSocketHeaders(Map<String,String> webSocketHeaders)	Sets map of custom websocket headers.
void	setWorkDir(Path workDir)	Specified a path to the work directory.
void	startEngine()	Starts the engine.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Details

REMOTING_MINIMUM_VERSION_HEADER

public static final String REMOTING_MINIMUM_VERSION_HEADER

HTTP header sent by Jenkins to indicate the earliest version of Remoting it is prepared to accept connections from.

See Also:

• Constant Field Values

WEBSOCKET_COOKIE_HEADER

public static final String WEBSOCKET_COOKIE_HEADER

The header name to be used for the connection cookie when using websockets.

See Also:

• Constant Field Values

listener

@Deprecated
public final EngineListener listener

Deprecated.

Use events.

workDir

@CheckForNull
public Path workDir

Specifies a default working directory of the remoting instance. If specified, this directory will be used to store logs, JAR cache, etc.

In order to retain compatibility, the option is disabled by default.

Jenkins specifics: This working directory is expected to be equal to the agent root specified in Jenkins configuration.

Since:

3.8

internalDir

@NonNull
public String internalDir

Specifies a directory within workDir, which stores all the remoting-internal files.

This option is not expected to be used frequently, but it allows remoting users to specify a custom storage directory if the default remoting directory is consumed by other stuff.

Since:

3.8

failIfWorkDirIsMissing

public boolean failIfWorkDirIsMissing

Fail the initialization if the workDir or internalDir are missing. This option presumes that the workspace structure gets initialized previously in order to ensure that we do not start up with a borked instance (e.g. if a filesystem mount gets disconnected).

Since:

3.8

Constructor Details

Engine

public Engine(EngineListener listener,
 List<URL> hudsonUrls,
 String secretKey,
 String agentName)

Engine

public Engine(EngineListener listener,
 List<URL> hudsonUrls,
 String secretKey,
 String agentName,
 String directConnection,
 String instanceIdentity,
 Set<String> protocols)

Method Details

startEngine

public void startEngine()
                 throws IOException

Starts the engine. The procedure initializes the working directory and all the required environment

Throws:

IOException - Initialization error

Since:

3.9

setJarCache

public void setJarCache(@NonNull
 JarCache jarCache)

Configures custom JAR Cache location. This option disables JAR Caching in the working directory.

Parameters:

jarCache - JAR Cache to be used

Since:

2.24

setLoggingConfigFile

public void setLoggingConfigFile(@NonNull
 Path filePath)

Sets path to the property file with JUL settings.

Parameters:

filePath - JAR Cache to be used

Since:

3.8

getHudsonUrl

@CheckForNull
public URL getHudsonUrl()

Provides Jenkins URL if available.

Returns:

Jenkins URL. May return null if the connection is not established or if the URL cannot be determined in the JnlpAgentEndpointResolver.

setWebSocket

public void setWebSocket(boolean webSocket)

setWebSocketHeaders

public void setWebSocketHeaders(@NonNull
 Map<String,String> webSocketHeaders)

Sets map of custom websocket headers. These headers will be applied to the websocket connection to Jenkins.

Parameters:

webSocketHeaders - a map of the headers to apply to the websocket connection

setTunnel

public void setTunnel(@CheckForNull
 String tunnel)

If set, connect to the specified host and port instead of connecting directly to Jenkins.

Parameters:

tunnel - Value. null to disable tunneling

setCredentials

public void setCredentials(String creds)

setProxyCredentials

public void setProxyCredentials(String proxyCredentials)

setNoReconnect

public void setNoReconnect(boolean noReconnect)

setNoReconnectAfter

public void setNoReconnectAfter(@CheckForNull
 Duration noReconnectAfter)

isDisableHttpsCertValidation

public boolean isDisableHttpsCertValidation()

Determines if JNLPAgentEndpointResolver will not perform certificate validation in the HTTPs mode.

Returns:

true if the certificate validation is disabled.

setDisableHttpsCertValidation

public void setDisableHttpsCertValidation(boolean disableHttpsCertValidation)

Sets if JNLPAgentEndpointResolver will not perform certificate validation in the HTTPs mode.

Parameters:

disableHttpsCertValidation - true if the certificate validation is disabled.

setAgentLog

public void setAgentLog(@CheckForNull
 Path agentLog)

Sets the destination for agent logs.

Parameters:

agentLog - Path to the agent log. If null, the engine will pick the default behavior depending on the workDir value

Since:

3.8

setWorkDir

public void setWorkDir(@CheckForNull
 Path workDir)

Specified a path to the work directory.

Parameters:

workDir - Path to the working directory of the remoting instance. null Disables the working directory.

Since:

3.8

setInternalDir

public void setInternalDir(@NonNull
 String internalDir)

Specifies name of the internal data directory within workDir.

Parameters:

internalDir - Directory name

Since:

3.8

setFailIfWorkDirIsMissing

public void setFailIfWorkDirIsMissing(boolean failIfWorkDirIsMissing)

Sets up behavior if the workDir or internalDir are missing during the startup. This option presumes that the workspace structure gets initialized previously in order to ensure that we do not start up with a borked instance (e.g. if a filesystem mount gets disconnected).

Parameters:

failIfWorkDirIsMissing - Flag

Since:

3.8

isKeepAlive

public boolean isKeepAlive()

Returns true if and only if the socket to the controller will have Socket.setKeepAlive(boolean) set.

Returns:

true if and only if the socket to the controller will have Socket.setKeepAlive(boolean) set.

setKeepAlive

public void setKeepAlive(boolean keepAlive)

Sets the Socket.setKeepAlive(boolean) to use for the connection to the controller.

Parameters:

keepAlive - the Socket.setKeepAlive(boolean) to use for the connection to the controller.

setCandidateCertificates

public void setCandidateCertificates(List<X509Certificate> candidateCertificates)

addCandidateCertificate

public void addCandidateCertificate(X509Certificate certificate)

addListener

public void addListener(EngineListener el)

removeListener

public void removeListener(EngineListener el)

run

public void run()

Specified by:

run in interface Runnable

Overrides:

run in class Thread

current

public static Engine current()

When invoked from within remoted Callable (that is, from the thread that carries out the remote requests), this method returns the Engine in which the remote operations run.

getAgentName

public String getAgentName()

Get the agent name associated with this Engine instance.

Returns:

the agent name.

Since:

TODO

getProtocolName

public String getProtocolName()

Get the name of the communication protocol used in this Engine instance. When the channel is not established by Engine (that is, current()) returns null), use Launcher.getCommunicationProtocolName() instead.

Returns:

the communication protocol name.

Since:

4.8