org.apache.lucene.replicator

## Interface Replicator

All Superinterfaces:
  AutoCloseable, Closeable

All Known Implementing Classes:
  HttpReplicator, LocalReplicator

    public interface Replicator
    extends Closeable

An interface for replicating files. Allows a producer to `publish` `Revision`s and consumers to `check for updates`. When a client needs to be updated, it is given a `SessionToken` through which it can `obtain` the files of that revision. After the client has finished obtaining all the files, it should `release` the given session, so that the files can be reclaimed if they are not needed anymore.

A client is always updated to the newest revision available. That is, if a client is on revision r1 and revisions r2 and r3 were published, then when the cllient will next check for update, it will receive r3.

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

### Method Summary

All Methods Instance Methods Abstract Methods
`SessionToken` `checkForUpdate(String currVersion)` Check whether the given version is up-to-date and returns a `SessionToken` which can be used for fetching the revision files, otherwise returns `null`.
`InputStream` `obtainFile(String sessionID, String source, String fileName)` Returns an `InputStream` for the requested file and source in the context of the given `session`.
`void` `publish(Revision revision)` Publish a new `Revision` for consumption by clients.
`void` `release(String sessionID)` Notify that the specified `SessionToken` is no longer needed by the caller.

### Methods inherited from interface java.io.Closeable

`close`

### Method Detail

#### publish

    void publish(Revision revision)
          throws IOException

Publish a new `Revision` for consumption by clients. It is the caller's responsibility to verify that the revision files exist and can be read by clients. When the revision is no longer needed, it will be `released` by the replicator.

Throws:
  `IOException`

#### checkForUpdate

    SessionToken checkForUpdate(String currVersion)
                         throws IOException

Check whether the given version is up-to-date and returns a `SessionToken` which can be used for fetching the revision files, otherwise returns `null`.

NOTE: when the returned session token is no longer needed, you should call `release(String)` so that the session resources can be reclaimed, including the revision files.

Throws:
  `IOException`

#### release

    void release(String sessionID)
          throws IOException

Notify that the specified `SessionToken` is no longer needed by the caller.

Throws:
  `IOException`

#### obtainFile

    InputStream obtainFile(String sessionID,
                           String source,
                           String fileName)
                    throws IOException

Returns an `InputStream` for the requested file and source in the context of the given `session`.

NOTE: it is the caller's responsibility to close the returned stream.

Throws:
  `SessionExpiredException` - if the specified session has already expired
  `IOException`