/**
* 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.waveprotocol.box.server.waveserver;
import org.waveprotocol.box.common.Receiver;
import org.waveprotocol.box.server.frontend.CommittedWaveletSnapshot;
import org.waveprotocol.wave.federation.Proto.ProtocolAppliedWaveletDelta;
import org.waveprotocol.wave.model.id.WaveletName;
import org.waveprotocol.wave.model.operation.wave.TransformedWaveletDelta;
import org.waveprotocol.wave.model.version.HashedVersion;
import org.waveprotocol.wave.model.wave.ParticipantId;
import org.waveprotocol.wave.model.wave.data.ObservableWaveletData;
import org.waveprotocol.wave.model.wave.data.ReadableWaveletData;
import com.google.common.base.Function;
/**
* Interface for a container class for a Wavelet's current state as well as its
* delta history. Local and remote wavelet interfaces inherit from this one.
*/
interface WaveletContainer {
/**
* Manufactures wavelet containers.
*
* @param <T> type manufactured by this factory.
*/
interface Factory<T extends WaveletContainer> {
/**
* @return a new wavelet container with the given wavelet name
*/
T create(WaveletNotificationSubscriber notifiee, WaveletName waveletName, String waveDomain);
}
/** Returns the name of the wavelet. */
WaveletName getWaveletName();
/** Returns a snapshot copy of the wavelet state. */
ObservableWaveletData copyWaveletData() throws WaveletStateException;
/** Returns a snapshot of the wavelet state, last committed version. */
CommittedWaveletSnapshot getSnapshot() throws WaveletStateException;
/**
* Provides read access to the inner state of the {@link WaveletContainer}.
*
* @param <T> the return type of the method.
* @param function the function to apply on the {@link ReadableWaveletData}.
* @return the output of the function.
* @throws WaveletStateException if the wavelet is in an unsuitable state.
*/
<T> T applyFunction(Function<ReadableWaveletData, T> function) throws WaveletStateException;
/**
* Retrieve the wavelet history of deltas applied to the wavelet.
*
* @param versionStart start version (inclusive), minimum 0.
* @param versionEnd end version (exclusive).
* @param receiver the deltas receiver.
* @throws AccessControlException if {@code versionStart} or
* {@code versionEnd} are not in the wavelet history.
* @throws WaveletStateException if the wavelet is in a state unsuitable for
* retrieving history.
*/
void requestHistory(HashedVersion versionStart, HashedVersion versionEnd,
Receiver<ByteStringMessage<ProtocolAppliedWaveletDelta>> receiver)
throws AccessControlException, WaveletStateException;
/**
* Retrieve the wavelet history of deltas applied to the wavelet, with
* additional safety check that
*
* @param versionStart start version (inclusive), minimum 0.
* @param versionEnd end version (exclusive).
* @param receiver the deltas receiver.
* @throws AccessControlException if {@code versionStart} or
* {@code versionEnd} are not in the wavelet history.
* @throws WaveletStateException if the wavelet is in a state unsuitable for
* retrieving history.
*/
void requestTransformedHistory(HashedVersion versionStart, HashedVersion versionEnd,
Receiver<TransformedWaveletDelta> receiver)
throws AccessControlException, WaveletStateException;
/**
* @param participantId id of participant attempting to gain access to
* wavelet, or null if the user isn't logged in.
* @throws WaveletStateException if the wavelet is in a state unsuitable for
* checking permissions.
* @return true if the participant is a participant on the wavelet or if the
* wavelet is empty or if a shared domain participant is participant
* on the wavelet.
*/
boolean checkAccessPermission(ParticipantId participantId) throws WaveletStateException;
/**
* The Last Committed Version returns when the local or remote wave server
* committed the wavelet.
*
* @throws WaveletStateException if the wavelet is in a state unsuitable for
* getting LCV.
*/
HashedVersion getLastCommittedVersion() throws WaveletStateException;
/**
* @return true if the participant id is a current participant of the wavelet.
* Each invocation acquires and releases the lock.
*/
boolean hasParticipant(ParticipantId participant) throws WaveletStateException;
/**
* @return the wavelet creator. This method doesn't acquire
* {@link WaveletContainer} lock since wavelet creator cannot change
* after wavelet creation and therefore it is save to concurrently
* read this property without lock.
*/
ParticipantId getCreator();
/**
* This method doesn't acquire {@link WaveletContainer} lock since shared
* domain participant cannot change and therefore it is safe to concurrently
* read this property without lock.
*
* @return the shared domain participant.
*/
public ParticipantId getSharedDomainParticipant();
/**
* @return true if the wavelet is at version zero, i.e., has no delta history
*/
boolean isEmpty() throws WaveletStateException;
}