/**
* Copyright 2010 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.box.server.robots;
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 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();
}