FarmWarDeployer (Apache Tomcat 8.5.96 API Documentation)

Package org.apache.catalina.ha.deploy

## Class FarmWarDeployer

- java.lang.Object
- - org.apache.catalina.ha.ClusterListener
  - - org.apache.catalina.ha.deploy.FarmWarDeployer

- All Implemented Interfaces:
    `ClusterDeployer`, `FileChangeListener`, `ChannelListener`

      public class FarmWarDeployer
      extends ClusterListener
      implements ClusterDeployer, FileChangeListener

  A farm war deployer is a class that is able to deploy/undeploy web applications in WAR from within the cluster.

  Any host can act as the admin, and will have three directories
  - watchDir - the directory where we watch for changes
  - deployDir - the directory where we install applications
  - tempDir - a temporaryDirectory to store binary data when downloading a war from the cluster
  Currently we only support deployment of WAR files since they are easier to send across the wire.
  Author:
    Peter Rossbach

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.io.File` | `configBase` | Path where context descriptors should be deployed.
    `protected java.lang.String` | `deployDir` | Deployment directory.
    `protected java.util.HashMap<java.lang.String,​FileMessageFactory>` | `fileFactories` |
    `protected Host` | `host` | The associated host.
    `protected int` | `maxValidTime` | The maximum valid time(in seconds) for FileMessageFactory.
    `protected javax.management.MBeanServer` | `mBeanServer` | MBean server.
    `protected javax.management.ObjectName` | `oname` | The associated deployer ObjectName.
    `protected int` | `processDeployFrequency` | Frequency of the Farm watchDir check.
    `protected boolean` | `started` |
    `protected java.lang.String` | `tempDir` | Temporary directory.
    `protected java.lang.String` | `watchDir` | Watch directory.
    `protected boolean` | `watchEnabled` |
    `protected WarWatcher` | `watcher` |

    - ### Fields inherited from class org.apache.catalina.ha.ClusterListener

      `cluster`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FarmWarDeployer()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `accept​(ClusterMessage msg)` | Before the cluster invokes messageReceived the cluster will ask the receiver to accept or decline the message, In the future, when messages get big, the accept method will only take a message header
    `protected void` | `addServiced​(java.lang.String name)` | Deprecated. Unused.
    `void` | `backgroundProcess()` | Call watcher to check for deploy changes
    `protected void` | `check​(java.lang.String name)` | Check a context for deployment operations.
    `protected boolean` | `copy​(java.io.File from, java.io.File to)` | Copy a file to the specified temp directory.
    `boolean` | `equals​(java.lang.Object listener)` |
    `void` | `fileModified​(java.io.File newWar)` | Modification from watchDir war detected!
    `void` | `fileRemoved​(java.io.File removeWar)` | War remove from watchDir
    `java.lang.String` | `getDeployDir()` |
    `java.io.File` | `getDeployDirFile()` |
    `FileMessageFactory` | `getFactory​(FileMessage msg)` | Create factory for all transported war files
    `int` | `getMaxValidTime()` |
    `int` | `getProcessDeployFrequency()` |
    `java.lang.String` | `getTempDir()` |
    `java.io.File` | `getTempDirFile()` |
    `java.lang.String` | `getWatchDir()` |
    `java.io.File` | `getWatchDirFile()` |
    `boolean` | `getWatchEnabled()` |
    `int` | `hashCode()` |
    `void` | `install​(java.lang.String contextName, java.io.File webapp)` | Install a new web application, whose web application archive is at the specified URL, into this container and all the other members of the cluster with the specified context name.
    `protected boolean` | `isServiced​(java.lang.String name)` | Deprecated. Unused.
    `boolean` | `isWatchEnabled()` |
    `void` | `messageReceived​(ClusterMessage msg)` | Callback from the cluster, when a message is received, The cluster will broadcast it invoking the messageReceived on the receiver.
    `protected void` | `remove​(java.lang.String contextName)` | Invoke the remove method on the deployer.
    `void` | `remove​(java.lang.String contextName, boolean undeploy)` | Remove an existing web application, attached to the specified context name.
    `void` | `removeFactory​(FileMessage msg)` | Remove file (war) from messages
    `protected void` | `removeInvalidFileFactories()` |
    `protected void` | `removeServiced​(java.lang.String name)` | Mark a context as no longer being serviced.
    `void` | `setDeployDir​(java.lang.String deployDir)` |
    `void` | `setMaxValidTime​(int maxValidTime)` |
    `void` | `setProcessDeployFrequency​(int processExpiresFrequency)` | Set the watcher checks frequency.
    `void` | `setTempDir​(java.lang.String tempDir)` |
    `void` | `setWatchDir​(java.lang.String watchDir)` |
    `void` | `setWatchEnabled​(boolean watchEnabled)` |
    `void` | `start()` | Start the cluster deployer, the owning container will invoke this
    `void` | `stop()` | Stops the cluster deployer, the owning container will invoke this
    `protected boolean` | `tryAddServiced​(java.lang.String name)` | Attempt to mark a context as being serviced
    `protected void` | `undeployDir​(java.io.File dir)` | Delete the specified directory, including all of its contents and subdirectories recursively.

    - ### Methods inherited from class org.apache.catalina.ha.ClusterListener

      `accept, getCluster, messageReceived, setCluster`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.catalina.tribes.ChannelListener

      `accept, messageReceived`

    - ### Methods inherited from interface org.apache.catalina.ha.ClusterDeployer

      `getCluster, setCluster`

- - ### Field Detail

    - #### started

          protected boolean started

    - #### fileFactories

          protected final java.util.HashMap<java.lang.String,​FileMessageFactory> fileFactories

    - #### deployDir

          protected java.lang.String deployDir

      Deployment directory.

    - #### tempDir

          protected java.lang.String tempDir

      Temporary directory.

    - #### watchDir

          protected java.lang.String watchDir

      Watch directory.

    - #### watchEnabled

          protected boolean watchEnabled

    - #### watcher

          protected WarWatcher watcher

    - #### processDeployFrequency

          protected int processDeployFrequency

      Frequency of the Farm watchDir check. Cluster wide deployment will be done once for the specified amount of backgroundProcess calls (ie, the lower the amount, the most often the checks will occur).

    - #### configBase

          protected java.io.File configBase

      Path where context descriptors should be deployed.

    - #### host

          protected Host host

      The associated host.

    - #### mBeanServer

          protected javax.management.MBeanServer mBeanServer

      MBean server.

    - #### oname

          protected javax.management.ObjectName oname

      The associated deployer ObjectName.

    - #### maxValidTime

          protected int maxValidTime

      The maximum valid time(in seconds) for FileMessageFactory.

  - ### Constructor Detail

    - #### FarmWarDeployer

          public FarmWarDeployer()

  - ### Method Detail

    - #### start

          public void start()
                     throws java.lang.Exception

      Description copied from interface: `ClusterDeployer`
      Start the cluster deployer, the owning container will invoke this
      Specified by:
        `start` in interface `ClusterDeployer`
      Throws:
        `java.lang.Exception` - - if failure to start cluster

    - #### stop

          public void stop()
                    throws LifecycleException

      Description copied from interface: `ClusterDeployer`
      Stops the cluster deployer, the owning container will invoke this
      Specified by:
        `stop` in interface `ClusterDeployer`
      Throws:
        `LifecycleException` - Error stopping cluster deployer

    - #### messageReceived

          public void messageReceived​(ClusterMessage msg)

      Callback from the cluster, when a message is received, The cluster will broadcast it invoking the messageReceived on the receiver.
      Specified by:
        `messageReceived` in class `ClusterListener`
      Parameters:
        `msg` - ClusterMessage - the message received from the cluster

    - #### getFactory

          public FileMessageFactory getFactory​(FileMessage msg)
                                        throws java.io.FileNotFoundException,
                                               java.io.IOException

      Create factory for all transported war files
      Parameters:
        `msg` - The file
      Returns:
        Factory for all app message (war files)
      Throws:
        `java.io.FileNotFoundException` - Missing file error
        `java.io.IOException` - Other IO error

    - #### removeFactory

          public void removeFactory​(FileMessage msg)

      Remove file (war) from messages
      Parameters:
        `msg` - The file

    - #### accept

          public boolean accept​(ClusterMessage msg)

      Before the cluster invokes messageReceived the cluster will ask the receiver to accept or decline the message, In the future, when messages get big, the accept method will only take a message header
      Specified by:
        `accept` in class `ClusterListener`
      Parameters:
        `msg` - ClusterMessage
      Returns:
        boolean - returns true to indicate that messageReceived should be invoked. If false is returned, the messageReceived method will not be invoked.

    - #### install

          public void install​(java.lang.String contextName,
                              java.io.File webapp)
                       throws java.io.IOException

      Install a new web application, whose web application archive is at the specified URL, into this container and all the other members of the cluster with the specified context name.

      If this application is successfully installed locally, a ContainerEvent of type `INSTALL_EVENT` will be sent to all registered listeners, with the newly created `Context` as an argument.

      Specified by:
        `install` in interface `ClusterDeployer`
      Parameters:
        `contextName` - The context name to which this application should be installed (must be unique)
        `webapp` - A WAR file or unpacked directory structure containing the web application to be installed
      Throws:
        `java.lang.IllegalArgumentException` - if the specified context name is malformed
        `java.lang.IllegalStateException` - if the specified context name is already deployed
        `java.io.IOException` - if an input/output error was encountered during installation

    - #### remove

          public void remove​(java.lang.String contextName,
                             boolean undeploy)
                      throws java.io.IOException

      Remove an existing web application, attached to the specified context name. If this application is successfully removed, a ContainerEvent of type `REMOVE_EVENT` will be sent to all registered listeners, with the removed `Context` as an argument. Deletes the web application war file and/or directory if they exist in the Host's appBase.
      Specified by:
        `remove` in interface `ClusterDeployer`
      Parameters:
        `contextName` - The context name of the application to be removed
        `undeploy` - boolean flag to remove web application from server
      Throws:
        `java.lang.IllegalArgumentException` - if the specified context name is malformed
        `java.lang.IllegalArgumentException` - if the specified context name does not identify a currently installed web application
        `java.io.IOException` - if an input/output error occurs during removal

    - #### fileModified

          public void fileModified​(java.io.File newWar)

      Modification from watchDir war detected!
      Specified by:
        `fileModified` in interface `FileChangeListener`
      See Also:
        `FileChangeListener.fileModified(File)`

    - #### fileRemoved

          public void fileRemoved​(java.io.File removeWar)

      War remove from watchDir
      Specified by:
        `fileRemoved` in interface `FileChangeListener`
      See Also:
        `FileChangeListener.fileRemoved(File)`

    - #### remove

          protected void remove​(java.lang.String contextName)
                         throws java.lang.Exception

      Invoke the remove method on the deployer.
      Parameters:
        `contextName` - The context to remove
      Throws:
        `java.lang.Exception` - If an error occurs removing the context

    - #### undeployDir

          protected void undeployDir​(java.io.File dir)

      Delete the specified directory, including all of its contents and subdirectories recursively.
      Parameters:
        `dir` - File object representing the directory to be deleted

    - #### backgroundProcess

          public void backgroundProcess()

      Call watcher to check for deploy changes
      Specified by:
        `backgroundProcess` in interface `ClusterDeployer`
      See Also:
        `ClusterDeployer.backgroundProcess()`

    - #### check

          protected void check​(java.lang.String name)
                        throws java.lang.Exception

      Check a context for deployment operations.
      Parameters:
        `name` - The context name
      Throws:
        `java.lang.Exception` - Error invoking the deployer

    - #### isServiced

          @Deprecated
          protected boolean isServiced​(java.lang.String name)
                                throws java.lang.Exception

      Deprecated.
      Unused. Will be removed in Tomcat 10.1.x onwards.
      Verified if a context is being services.
      Parameters:
        `name` - The context name
      Returns:
        `true` if the context is being serviced
      Throws:
        `java.lang.Exception` - Error invoking the deployer

    - #### addServiced

          @Deprecated
          protected void addServiced​(java.lang.String name)
                              throws java.lang.Exception

      Deprecated.
      Unused. Will be removed in Tomcat 10.1.x onwards. Use `tryAddServiced(java.lang.String)`
      Mark a context as being services.
      Parameters:
        `name` - The context name
      Throws:
        `java.lang.Exception` - Error invoking the deployer

    - #### tryAddServiced

          protected boolean tryAddServiced​(java.lang.String name)
                                    throws java.lang.Exception

      Attempt to mark a context as being serviced
      Parameters:
        `name` - The context name
      Returns:
        `true` if the application was marked as being serviced and `false` if the application was already marked as being serviced
      Throws:
        `java.lang.Exception` - Error invoking the deployer

    - #### removeServiced

          protected void removeServiced​(java.lang.String name)
                                 throws java.lang.Exception

      Mark a context as no longer being serviced.
      Parameters:
        `name` - The context name
      Throws:
        `java.lang.Exception` - Error invoking the deployer

    - #### equals

          public boolean equals​(java.lang.Object listener)

      Specified by:
        `equals` in interface `ChannelListener`
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `listener` - Object
      Returns:
        boolean
      See Also:
        `Object.equals(Object)`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `ChannelListener`
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        int
      See Also:
        `Object.hashCode()`

    - #### getDeployDir

          public java.lang.String getDeployDir()

    - #### getDeployDirFile

          public java.io.File getDeployDirFile()

    - #### setDeployDir

          public void setDeployDir​(java.lang.String deployDir)

    - #### getTempDir

          public java.lang.String getTempDir()

    - #### getTempDirFile

          public java.io.File getTempDirFile()

    - #### setTempDir

          public void setTempDir​(java.lang.String tempDir)

    - #### getWatchDir

          public java.lang.String getWatchDir()

    - #### getWatchDirFile

          public java.io.File getWatchDirFile()

    - #### setWatchDir

          public void setWatchDir​(java.lang.String watchDir)

    - #### isWatchEnabled

          public boolean isWatchEnabled()

    - #### getWatchEnabled

          public boolean getWatchEnabled()

    - #### setWatchEnabled

          public void setWatchEnabled​(boolean watchEnabled)

    - #### getProcessDeployFrequency

          public int getProcessDeployFrequency()

      Returns:
        the frequency of watcher checks.

    - #### setProcessDeployFrequency

          public void setProcessDeployFrequency​(int processExpiresFrequency)

      Set the watcher checks frequency.
      Parameters:
        `processExpiresFrequency` - the new manager checks frequency

    - #### getMaxValidTime

          public int getMaxValidTime()

    - #### setMaxValidTime

          public void setMaxValidTime​(int maxValidTime)

    - #### copy

          protected boolean copy​(java.io.File from,
                                 java.io.File to)

      Copy a file to the specified temp directory.
      Parameters:
        `from` - copy from temp
        `to` - to host appBase directory
      Returns:
        true, copy successful

    - #### removeInvalidFileFactories

          protected void removeInvalidFileFactories()