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
`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
`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
`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.