/**
* 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.robots;
import com.google.common.collect.ImmutableSet;
import com.google.wave.api.InvalidRequestException;
import com.google.wave.api.JsonRpcConstant.ParamsProperty;
import com.google.wave.api.OperationRequest;
import com.google.wave.api.data.converter.EventDataConverter;
import com.google.wave.api.event.Event;
import org.waveprotocol.box.server.robots.util.ConversationUtil;
import org.waveprotocol.wave.model.conversation.Conversation;
import org.waveprotocol.wave.model.conversation.ConversationBlip;
import org.waveprotocol.wave.model.conversation.ObservableConversationView;
import org.waveprotocol.wave.model.id.WaveId;
import org.waveprotocol.wave.model.id.WaveletId;
import org.waveprotocol.wave.model.wave.ParticipantId;
import org.waveprotocol.wave.model.wave.opbased.OpBasedWavelet;
import org.waveprotocol.wave.model.operation.wave.TransformedWaveletDelta;
import org.waveprotocol.box.server.frontend.CommittedWaveletSnapshot;
import org.waveprotocol.wave.model.id.WaveletName;
import org.waveprotocol.box.common.Receiver;
import org.waveprotocol.wave.model.version.HashedVersion;
import java.util.Map;
/**
* Context for performing robot operations.
*
* <p>
* {@link OperationContext} throws {@link InvalidRequestException} because it is
* expected to be used together with an {@link OperationRequest}.
*
* @author ljvderijk@google.com (Lennard de Rijk)
*/
public interface OperationContext {
/** Marks temporary wave and blip ID's since V2 */
final String TEMP_ID_MARKER = "TBD_";
/**
* @return true iff this context is bound to a wavelet.
*/
boolean isBound();
/**
* @param operationId the id of the robot operation.
* @return True iff a response has been set for the given id.
*/
boolean hasResponse(String operationId);
/**
* Constructs a response with the given data in its payload field.
*
* @param data the data to be put in the repsonse.
*/
void constructResponse(OperationRequest operation, Map<ParamsProperty, Object> data);
/**
* Constructs and stores a response signifying an error to be put in the
* context.
*
* @param errorMessage the error message to be put in the response.
*/
void constructErrorResponse(OperationRequest operation, String errorMessage);
/**
* Processes the event and sets the proper response.
*
* @param event the event to process.
* @throws InvalidRequestException If the event could not be properly
* processed.
*/
void processEvent(OperationRequest operation, Event event) throws InvalidRequestException;
/**
* Stores a reference from a temporary wavelet id to a real wavelet id. If the
* given id is not a temporary id no reference will be stored.
*
* @param waveId the wave id.
* @param waveletId the wavelet id.
* @param newWavelet the new wavelet to remember.
*/
void putWavelet(WaveId waveId, WaveletId waveletId, RobotWaveletData newWavelet);
/**
* Opens a wavelet for the given wave id and wavelet id. Note: Usually if the
* wavelet for specified wavelet id doesn't exist - the method returns
* null. However, for user data wavelets the method will create a new empty one
* and return it.
*
* @param waveId the wave id of the wavelet to open.
* @param waveletId the wavelet id of the wavelet to open.
* @param participant the id of the participant that wants to open the
* wavelet.
* @throws InvalidRequestException if the wavelet can not be opened.
*/
OpBasedWavelet openWavelet(WaveId waveId, WaveletId waveletId, ParticipantId participant)
throws InvalidRequestException;
/**
* Opens the wavelet specified in the given operation. Note: Usually if the
* wavelet for specified wavelet id doesn't exist - the method returns
* null. However, for user data wavelets the method will create a new empty one
* and return it.
*
* @param operation the operation specifying which wavelet to open.
* @param participant the id of the participant that wants to open the
* wavelet.
* @throws InvalidRequestException if the wavelet can not be opened or the
* operation does not define the wave and wavelet id.
*/
OpBasedWavelet openWavelet(OperationRequest operation, ParticipantId participant)
throws InvalidRequestException;
/**
* Gets the conversation for of wavelet for the given wave id and wavelet id.
* Tries to retrieve and open the wavelet if that has not already been done.
*
* @param waveId the wave id of the wavelet.
* @param waveletId the wavelet id of.
* @param participant the id of the participant that wants to operation on the
* conversation.
* @throws InvalidRequestException if the wavelet can not be opened.
*/
ObservableConversationView openConversation(
WaveId waveId, WaveletId waveletId, ParticipantId participant) throws InvalidRequestException;
/**
* Gets the conversation for of wavelet specified in the operation. Tries to
* retrieve and open the wavelet if that has not already been done.
*
* @param operation the operation specifying which wavelet to get the
* conversation for.
* @param participant the id of the participant that wants to operation on the
* conversation.
* @throws InvalidRequestException if the wavelet can not be opened or the
* operation does not define the wave and wavelet id.
*/
ObservableConversationView openConversation(OperationRequest operation, ParticipantId participant)
throws InvalidRequestException;
/**
* Stores a reference from a temporary blip id to a real blip id. If the given
* id is not a temporary id it will be ignored.
*
* @param blipId the temporary blip id.
* @param newBlip the blip that this id should reference.
*/
void putBlip(String blipId, ConversationBlip newBlip);
/**
* Retrieve a blip with the given, possible temporary id, from the
* conversation.
*
* @param conversation the conversation the blip belongs to.
* @param blipId the id of the blip, may be be a temporary id.
* @throws InvalidRequestException if the blip could not be retrieved or has
* been deleted.
*/
ConversationBlip getBlip(Conversation conversation, String blipId) throws InvalidRequestException;
/**
* @return the converter to convert to API objects
*/
EventDataConverter getConverter();
/**
* Returns {@link ConversationUtil} which is used to generate conversations
* and ids.
*/
ConversationUtil getConversationUtil();
/**
* Gets the list of wavelet Ids that are visible to the user.
*
* @param operation the operation specifying wave.
* @param participant the user.
* @return set of wavelet Ids, visible to the user.
*/
ImmutableSet<WaveletId> getVisibleWaveletIds(OperationRequest operation, ParticipantId participant)
throws InvalidRequestException;
/**
* Takes snapshot of a wavelet, checking access for the given participant.
*
* @param waveletName the wavelet name of the wavelet to get.
* @param participant the user.
* @return snapshot on success, null on failure
*/
CommittedWaveletSnapshot getWaveletSnapshot(WaveletName waveletName, ParticipantId participant)
throws InvalidRequestException;
/**
* Takes deltas history of a wavelet, checking access for the given participant.
*
* @param waveletName the wavelet name of the wavelet to get.
* @param participant the user.
* @param fromVersion start version (inclusive), minimum 0.
* @param toVersion start version (exclusive).
* @param receiver the transformed deltas receiver.
*/
void getDeltas(WaveletName waveletName, ParticipantId participant,
HashedVersion fromVersion, HashedVersion toVersion, Receiver<TransformedWaveletDelta> receiver)
throws InvalidRequestException;
}