Class Engine

  • All Implemented Interfaces:
    Runnable

    @NotThreadSafe
    public class Engine
    extends Thread
    Agent engine that proactively connects to Jenkins controller.
    Author:
    Kohsuke Kawaguchi
    • Field Detail

      • 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
      • 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
    • Method Detail

      • 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)
      • 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
      • setCandidateCertificates

        public void setCandidateCertificates​(List<X509Certificate> candidateCertificates)
      • addCandidateCertificate

        public void addCandidateCertificate​(X509Certificate certificate)
      • 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