Class DeploymentScanner

java.lang.Object
org.eclipse.jetty.util.component.AbstractLifeCycle
org.eclipse.jetty.util.component.ContainerLifeCycle
org.eclipse.jetty.deploy.DeploymentScanner
All Implemented Interfaces:
Container, Destroyable, Dumpable, Dumpable.DumpableContainer, LifeCycle, Scanner.BulkListener, Scanner.Listener
@ManagedObject("Provider for dynamic deployment of contexts (and webapps) based on presence in directory") public class DeploymentScanner extends ContainerLifeCycle implements Scanner.BulkListener

Jetty WebApp Hot Deployment Scanner.

This class scans one or more directories (typically "webapps") for web applications to deploy, which may be:

  • A standard WAR file (must end in ".war")
  • A directory containing an expanded WAR file
  • A directory containing static content
  • An XML descriptor in XmlConfiguration format that configures a ContextHandler instance
Once a collection of files that represent a web application is found (or updated), an instance of ContextHandlerFactory is used to create a ContextHandler, which is then deployed/undeployed via a Deployer instance. The instances of the Deployer and ContextHandlerFactory used can either be:
  • Passed into a constructor of this class
  • Discovered as a {Container.getBean(Class) bean} of the Server instance
  • Default implementations instantiated by this class.

To avoid double deployments and allow flexibility of the content of the scanned directories, the provider implements some heuristics to ignore some files found in the scans:

  • Hidden files (starting with ".") are ignored
  • Directories with names ending in ".d" are ignored
  • Property files with names ending in ".properties" are not deployed.
  • If a directory and a WAR file exist (eg: foo/ and foo.war) then the directory is assumed to be the unpacked WAR and only the WAR file is deployed (which may reuse the unpacked directory)
  • If a directory and a matching XML file exist (eg: foo/ and foo.xml) then the directory is assumed to be an unpacked WAR and only the XML file is deployed (which may use the directory in its configuration)
  • If a WAR file and a matching XML file exist (eg: foo.war and foo.xml) then the WAR file is assumed to be configured by the XML file and only the XML file is deployed.

For XML configured contexts, the following is available.

  • The XML Object ID Map will have a reference to the Server instance via the ID name "Server"
  • The Default XML Properties are populated from a call to XmlConfiguration.setJettyStandardIdsAndProperties(Object, Path) (for things like jetty.home and jetty.base)
  • An extra XML Property named "jetty.webapps" is available, and points to the webapps path.

Context Deployment properties will be initialized with:

  • The properties set on the application via embedded calls modifying DeploymentScanner.PathsApp.getAttributes()
  • The app specific properties file webapps/<webapp-name>.properties
  • The environment specific properties file webapps/<environment-name>[-zzz].properties
  • The Attributes from the Environment

To configure Environment specific deployment Attributes, either set the appropriate Deployable attribute via Attributes.setAttribute(String, Object), or use the convenience class DeploymentScanner.EnvironmentConfig. 

DeploymentScanner provider = new DeploymentScanner();
EnvironmentConfig env10config = provider.configureEnvironment("ee10");
env10config.setExtractWars(true);
env10config.setParentLoaderPriority(false);

  • Constructor Details

    • DeploymentScanner

      public DeploymentScanner(@Name("server") Server server)

      Construct a raw DeploymentScanner that will (periodically) scan specific directories for paths that can be used to construct webapps that will be submitted to the Deployer for eventual deployment to its configured destination.

      Parameters:
      server - the server reference to use for any XML based deployments.

    • DeploymentScanner

      public DeploymentScanner(@Name("server") Server server, @Name("deployer") Deployer deployer)

      Construct a raw DeploymentScanner that will (periodically) scan specific directories for paths that can be used to construct webapps that will be submitted to the Deployer for eventual deployment to its configured destination.

      Parameters:
      server - the server reference to use for any XML based deployments.
      deployer - the Deployer to use for deploying the created ContextHandlers, or null for a default.

    • DeploymentScanner

      public DeploymentScanner(@Name("server") Server server, @Name("deployer") Deployer deployer, @Name("filenameFilter") FilenameFilter filter)

      Construct a raw DeploymentScanner that will (periodically) scan specific directories for paths that can be used to construct webapps that will be submitted to the Deployer for eventual deployment to its configured destination.

      Parameters:
      server - the server reference to use for any XML based deployments.
      deployer - the Deployer to use for deploying the created ContextHandlers, or null for a default.
      filter - A custom FilenameFilter to control what files the Scanner monitors for changes, or null for a default.

    • DeploymentScanner

      public DeploymentScanner(@Name("server") Server server, @Name("deployer") Deployer deployer, @Name("contextHandlerFactory") ContextHandlerFactory contextHandlerFactory)

      Construct a raw DeploymentScanner that will (periodically) scan specific directories for paths that can be used to construct webapps that will be submitted to the Deployer for eventual deployment to its configured destination.

      Parameters:
      server - the server reference to use for any XML based deployments.
      deployer - the Deployer to use for deploying the created ContextHandlers, or null for a default.
      contextHandlerFactory - The factory to use to create ContextHandlers, or null for a default.

    • DeploymentScanner

      public DeploymentScanner(@Name("server") Server server, @Name("deployer") Deployer deployer, @Name("filenameFilter") FilenameFilter filter, @Name("contextHandlerFactory") ContextHandlerFactory contextHandlerFactory)

      Construct a raw DeploymentScanner that will (periodically) scan specific directories for paths that can be used to construct webapps that will be submitted to the Deployer for eventual deployment to its configured destination.

      Parameters:
      server - the server reference to use for any XML based deployments.
      deployer - the Deployer to use for deploying the created ContextHandlers, or null for a default.
      filter - A custom FilenameFilter to control what files the Scanner monitors for changes, or null for a default
      contextHandlerFactory - The factory to use to create ContextHandlers, or null for a default.

  • Method Details

    • addWebappsDirectory

      public void addWebappsDirectory(Path dir)
      Parameters:
      dir - Directory to scan for deployable artifacts

    • configureEnvironment

      public DeploymentScanner.EnvironmentConfig configureEnvironment(String name)
      Configure the Environment specific Deploy settings.
      Parameters:
      name - the name of the environment.
      Returns:
      the deployment configuration for the Environment.

    • dump

      public void dump(Appendable out, String indent) throws IOException
      Description copied from interface: Dumpable
      Dump this object (and children) into an Appendable using the provided indent after any new lines. The indent should not be applied to the first object dumped.
      Specified by:
      dump in interface Dumpable
      Overrides:
      dump in class ContainerLifeCycle
      Parameters:
      out - The appendable to dump to
      indent - The indent to apply after any new lines.
      Throws:
      IOException - if unable to write to Appendable

    • getActionComparator

      public Comparator<DeploymentScanner.DeployAction> getActionComparator()
      Returns:
      The Comparator used to sort the DeploymentScanner.DeployActions before acting on them.

    • setActionComparator

      public void setActionComparator(Comparator<DeploymentScanner.DeployAction> actionComparator)

    • getEnvironmentsOrder

      public List<String> getEnvironmentsOrder()

    • setEnvironmentsOrder

      public void setEnvironmentsOrder(List<String> environmentsOrder)

    • getEnvironmentsDirectory

      public Path getEnvironmentsDirectory()
      Returns:
      The Path of the directory to scan for environment configuration files, or null

    • setEnvironmentsDirectory

      public void setEnvironmentsDirectory(Path dir)

    • getWebappDirectories

      @Deprecated(since="12.1.2", forRemoval=true) public List<Path> getWebappDirectories()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getWebappsDirectories() instead
      Returns:
      The List of Paths scanned for files to deploy.

    • getWebappsDirectories

      public List<Path> getWebappsDirectories()
      Returns:
      the List of Paths that are scanned to deploy web applications

    • setWebappDirectories

      @Deprecated(since="12.1.2", forRemoval=true) public void setWebappDirectories(Collection<Path> directories)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setWebappsDirectories(Collection) instead
      Parameters:
      directories - The List of Paths scanned for files to deploy.

    • setWebappsDirectories

      public void setWebappsDirectories(Collection<Path> directories)
      Parameters:
      directories - the List of Paths that are scanned to deploy web applications

    • getScanInterval

      @ManagedAttribute("scanning interval to detect changes which need reloaded") public int getScanInterval()
      Returns:
      scan interval (in seconds) to detect changes which need reloaded
      See Also:

    • setScanInterval

      public void setScanInterval(int scanInterval)
      Parameters:
      scanInterval - scan interval (in seconds) to detect changes which need reloaded
      See Also:

    • isDeferInitialScan

      public boolean isDeferInitialScan()
      Test if initial scan should be deferred.
      Returns:
      true if initial scan is deferred, false to have initial scan occur on startup of DeploymentScanner.

    • setDeferInitialScan

      public void setDeferInitialScan(boolean defer)
      Flag to control initial scan behavior.
      • true - to have initial scan deferred until the Server component has reached its STARTED state.
        Note: any failures in a deployment will not fail the Server startup in this mode.
      • false - (default value) to have initial scan occur as normal on DeploymentScanner startup.
      Parameters:
      defer - true to defer initial scan, false to have initial scan occur on startup of DeploymentScanner.

    • isUseRealPaths

      public boolean isUseRealPaths()
      If Scanner is configured to reportRealPaths.
      Returns:
      True if the real path of the scanned files should be used for deployment.
      See Also:

    • setUseRealPaths

      public void setUseRealPaths(boolean useRealPaths)
      Tells Scanner to reportRealPaths.
      Parameters:
      useRealPaths - True if the real path of the scanned files should be used for deployment.
      See Also:

    • pathsChanged

      public void pathsChanged(Map<Path, Scanner.Notification> changeSet)
      This is the listener event for Scanner to report changes.
      Specified by:
      pathsChanged in interface Scanner.BulkListener
      Parameters:
      changeSet - the changeset from the Scanner.

    • scan

      @ManagedOperation(value="Scan the webapps directories", impact="ACTION") public void scan()

    • doStart

      protected void doStart() throws Exception
      Description copied from class: ContainerLifeCycle
      Starts the managed lifecycle beans in the order they were added.
      Overrides:
      doStart in class ContainerLifeCycle
      Throws:
      Exception - If there was a problem starting. Will cause a transition to FAILED state

    • doStop

      protected void doStop() throws Exception
      Description copied from class: ContainerLifeCycle
      Stops the managed lifecycle beans in the reverse order they were added.
      Overrides:
      doStop in class ContainerLifeCycle
      Throws:
      Exception - If there was a problem stopping. Will cause a transition to FAILED state

    • toString

      public String toString()
      Overrides:
      toString in class AbstractLifeCycle