org.apache.lucene.replicator

## Class ReplicationClient

- java.lang.Object
- - org.apache.lucene.replicator.ReplicationClient

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class ReplicationClient
      extends Object
      implements Closeable

  A client which monitors and obtains new revisions from a `Replicator`. It can be used to either periodically check for updates by invoking `startUpdateThread(long, java.lang.String)`, or manually by calling `updateNow()`.

  Whenever a new revision is available, the `requiredFiles(Map)` are copied to the `Directory` specified by `PerSessionDirectoryFactory` and a handler is notified.

  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ReplicationClient.ReplicationHandler` Handler for revisions obtained by the client.
    `static interface` | `ReplicationClient.SourceDirectoryFactory` Resolves a session and source into a `Directory` to use for copying the session files to.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `INFO_STREAM_COMPONENT` The component name to use with `InfoStream.isEnabled(String)`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReplicationClient(Replicator replicator, ReplicationClient.ReplicationHandler handler, ReplicationClient.SourceDirectoryFactory factory)` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `protected void` | `ensureOpen()` Throws `AlreadyClosedException` if the client has already been closed.
    `protected void` | `handleUpdateException(Throwable t)` Called when an exception is hit by the replication thread.
    `boolean` | `isUpdateThreadAlive()` Returns true if the update thread is alive.
    `protected Map<String,List<RevisionFile>>` | `requiredFiles(Map<String,List<RevisionFile>> newRevisionFiles)` Returns the files required for replication.
    `void` | `setInfoStream(InfoStream infoStream)` Sets the `InfoStream` to use for logging messages.
    `void` | `startUpdateThread(long intervalMillis, String threadName)` Start the update thread with the specified interval in milliseconds.
    `void` | `stopUpdateThread()` Stop the update thread.
    `String` | `toString()`
    `void` | `updateNow()` Executes the update operation immediately, irregardless if an update thread is running or not.

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

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

- - ### Field Detail

    - #### INFO_STREAM_COMPONENT

          public static final String INFO_STREAM_COMPONENT

      The component name to use with `InfoStream.isEnabled(String)`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ReplicationClient

          public ReplicationClient(Replicator replicator,
                                   ReplicationClient.ReplicationHandler handler,
                                   ReplicationClient.SourceDirectoryFactory factory)

      Constructor.
      Parameters:
        `replicator` - the `Replicator` used for checking for updates
        `handler` - notified when new revisions are ready
        `factory` - returns a `Directory` for a given source and session

  - ### Method Detail

    - #### ensureOpen

          protected final void ensureOpen()

      Throws `AlreadyClosedException` if the client has already been closed.

    - #### handleUpdateException

          protected void handleUpdateException(Throwable t)

      Called when an exception is hit by the replication thread. The default implementation prints the full stacktrace to the `InfoStream` set in `setInfoStream(InfoStream)`, or the `default` one. You can override to log the exception elswhere.

      NOTE: if you override this method to throw the exception further, the replication thread will be terminated. The only way to restart it is to call `stopUpdateThread()` followed by `startUpdateThread(long, String)`.

    - #### requiredFiles

          protected Map<String,List<RevisionFile>> requiredFiles(Map<String,List<RevisionFile>> newRevisionFiles)

      Returns the files required for replication. By default, this method returns all files that exist in the new revision, but not in the handler.

    - #### close

          public void close()

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`

    - #### startUpdateThread

          public void startUpdateThread(long intervalMillis,
                                        String threadName)

      Start the update thread with the specified interval in milliseconds. For debugging purposes, you can optionally set the name to set on `Thread.setName(String)`. If you pass `null`, a default name will be set.
      Throws:
        `IllegalStateException` - if the thread has already been started

    - #### stopUpdateThread

          public void stopUpdateThread()

      Stop the update thread. If the update thread is not running, silently does nothing. This method returns after the update thread has stopped.

    - #### isUpdateThreadAlive

          public boolean isUpdateThreadAlive()

      Returns true if the update thread is alive. The update thread is alive if it has been `started` and not `stopped`, as well as didn't hit an error which caused it to terminate (i.e. `handleUpdateException(Throwable)` threw the exception further).

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### updateNow

          public void updateNow()
                         throws IOException

      Executes the update operation immediately, irregardless if an update thread is running or not.
      Throws:
        `IOException`

    - #### setInfoStream

          public void setInfoStream(InfoStream infoStream)

      Sets the `InfoStream` to use for logging messages.

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.