/**
* Copyright 2009 Google Inc.
*
* Licensed 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.waveprotocol.wave.federation;
import com.google.protobuf.ByteString;
import org.waveprotocol.wave.federation.FederationErrorProto.FederationError;
import org.waveprotocol.wave.federation.Proto.ProtocolHashedVersion;
import org.waveprotocol.wave.federation.Proto.ProtocolSignedDelta;
import org.waveprotocol.wave.federation.Proto.ProtocolSignerInfo;
import org.waveprotocol.wave.model.id.WaveletName;
import java.util.List;
/**
* The WaveletFederationProvider is an interface that should be implemented by
* the provider, or host, of wavelets. It may be used to pass requests upstream
* with the intention of eventually hitting the authoritative master of a
* specific wavelet. This interface forms one half of the Federation Bus when
* paired with a WaveletFederationListener.
*
* This should be implemented by both the Wavelet Server and the Federation
* Remote. The Federation Remote will then be able to forward these requests out
* over-the-wire to the relevant federated server. The Wavelet Server will
* receive requests over this interface from the Federation Host, i.e., from
* remote servers seeking information of wavelets authoritatively hosted here.
*
* @author jochen@google.com (Jochen Bekmann)
*/
public interface WaveletFederationProvider {
/**
* Base interface for federation listeners which can fail with a federation error code.
*/
interface FederationListener {
/**
* Called when a request fails.
*/
void onFailure(FederationError errorMessage);
}
/**
* Request submission of signed delta.
*
* @param waveletName name of wavelet.
* @param delta delta signed by the submitting WSP.
* @param listener callback for the result.
*/
void submitRequest(WaveletName waveletName, ProtocolSignedDelta delta,
SubmitResultListener listener);
interface SubmitResultListener extends FederationListener {
/**
* Called when a submit succeeds.
*
* @param operationsApplied number of ops applied
* @param hashedVersionAfterApplication wavelet version after the delta
* @param applicationTimestamp timestamp of the application
*/
void onSuccess(int operationsApplied, ProtocolHashedVersion hashedVersionAfterApplication,
long applicationTimestamp);
}
/**
* Retrieve delta history for the given wavelet.
*
* @param waveletName name of wavelet.
* @param domain the domain of the requester, used to determine whether there is
* a user on the wavelet matching the domain to the requester.
* @param startVersion beginning of range (inclusive), minimum 0.
* @param endVersion end of range (exclusive).
* @param lengthLimit estimated size, in bytes, as an upper limit on the amount of data
* returned.
* @param listener callback for the result.
*/
void requestHistory(WaveletName waveletName, String domain,
ProtocolHashedVersion startVersion, ProtocolHashedVersion endVersion,
long lengthLimit, HistoryResponseListener listener);
interface HistoryResponseListener extends FederationListener {
/**
* @param deltaList of serialised {@code ProtocolAppliedWaveletDelta}s, represented as
* {@code ByteString}s. Note that these are not guaranteed to parse correctly as
* applied deltas, so it is up to the implementation of onSuccess to deal with this.
* @param lastCommittedVersion of the wavelet that is committed to persistent
* storage, if smaller than the end version of deltas, null otherwise
* @param versionTruncatedAt the end version of the deltas if less than the
* requested endVersion in the call to {@code requestHistory}
*/
void onSuccess(List<ByteString> deltaList,
ProtocolHashedVersion lastCommittedVersion, long versionTruncatedAt);
}
/**
* Retrieve info for a signer of an applied delta.
*
* This is called by a federation remote when it receives an applied delta from
* a call to requestHistory or from a wavelet update and it doesn't already have
* the info for a signer of the delta.
*
* If you host a wavelet, you MUST maintain a copy of the SignerInfo of every signer used to
* sign any applied delta in the delta history and serve it to anyone who knows the hashed
* version of the wavelet immediately after the delta was applied.
*
* @param signerId the identifier of the signer (the hash of its certificate chain)
* @param waveletName name of wavelet that the delta belongs to.
* @param deltaEndVersion the version of the wavelet immediately after the delta was applied.
* @param listener callback for the result.
*/
void getDeltaSignerInfo(ByteString signerId,
WaveletName waveletName, ProtocolHashedVersion deltaEndVersion,
DeltaSignerInfoResponseListener listener);
interface DeltaSignerInfoResponseListener extends FederationListener {
void onSuccess(ProtocolSignerInfo signerInfo);
}
/**
* Post signer info. This should be called in advance of any call to submitRequest
* with a delta signed by the signer with this info.
*
* @param destinationDomain the domain to post this signer info to.
* @param signerInfo info of a signer.
* @param listener callback for the result.
*/
void postSignerInfo(String destinationDomain, ProtocolSignerInfo signerInfo,
PostSignerInfoResponseListener listener);
interface PostSignerInfoResponseListener extends FederationListener {
void onSuccess();
}
}