| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.lucene.replicator; |
| |
| import java.io.Closeable; |
| import java.io.IOException; |
| import java.io.InputStream; |
| |
| /** |
| * An interface for replicating files. Allows a producer to |
| * {@link #publish(Revision) publish} {@link Revision}s and consumers to |
| * {@link #checkForUpdate(String) check for updates}. When a client needs to be |
| * updated, it is given a {@link SessionToken} through which it can |
| * {@link #obtainFile(String, String, String) obtain} the files of that |
| * revision. After the client has finished obtaining all the files, it should |
| * {@link #release(String) release} the given session, so that the files can be |
| * reclaimed if they are not needed anymore. |
| * <p> |
| * A client is always updated to the newest revision available. That is, if a |
| * client is on revision <em>r1</em> and revisions <em>r2</em> and <em>r3</em> |
| * were published, then when the cllient will next check for update, it will |
| * receive <em>r3</em>. |
| * |
| * @lucene.experimental |
| */ |
| public interface Replicator extends Closeable { |
| |
| /** |
| * Publish a new {@link 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 |
| * {@link Revision#release() released} by the replicator. |
| */ |
| public void publish(Revision revision) throws IOException; |
| |
| /** |
| * Check whether the given version is up-to-date and returns a |
| * {@link SessionToken} which can be used for fetching the revision files, |
| * otherwise returns {@code null}. |
| * <p> |
| * <b>NOTE:</b> when the returned session token is no longer needed, you |
| * should call {@link #release(String)} so that the session resources can be |
| * reclaimed, including the revision files. |
| */ |
| public SessionToken checkForUpdate(String currVersion) throws IOException; |
| |
| /** |
| * Notify that the specified {@link SessionToken} is no longer needed by the |
| * caller. |
| */ |
| public void release(String sessionID) throws IOException; |
| |
| /** |
| * Returns an {@link InputStream} for the requested file and source in the |
| * context of the given {@link SessionToken#id session}. |
| * <p> |
| * <b>NOTE:</b> it is the caller's responsibility to close the returned |
| * stream. |
| * |
| * @throws SessionExpiredException if the specified session has already |
| * expired |
| */ |
| public InputStream obtainFile(String sessionID, String source, String fileName) throws IOException; |
| |
| } |