/**
 * Copyright 2011 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.register;

import org.waveprotocol.box.server.account.RobotAccountData;
import org.waveprotocol.box.server.persistence.PersistenceException;
import org.waveprotocol.box.server.robots.util.RobotsUtil.RobotRegistrationException;
import org.waveprotocol.wave.model.wave.ParticipantId;

/**
 * Provides robot un/registration services.
 *
 * @author yurize@apache.org (Yuri Zelikov)
 */
public interface RobotRegistrar {

  /** Receives robot un/registration events. */
  public interface Listener {

    /** Invoked after the robot account was created and added to the account store. */
    public void onRegistrationSuccess(RobotAccountData account);

    /** Invoked after the robot account was removed from the account store. */
    public void onUnregistrationSuccess(RobotAccountData account);
  }

  /**
   * Registers a new robot account.
   *
   * @param robotId the robotId to register.
   * @param location the location of the robot (URI).
   * @return the newly registered robot account.
   * @throws RobotRegistrationException if account for this id already exist.
   * @throws PersistenceException if the persistence layer reports an error.
   */
  public RobotAccountData registerNew(ParticipantId robotId, String location)
      throws RobotRegistrationException, PersistenceException;

  /**
   * Unregisters a robot by removing it from the account store.
   *
   * @param robotId the id to remove.
   * @return the account data of the removed robot or
   *         <code>null</null> if no such robot account exist.
   * @throws RobotRegistrationException if the id to remove exist but is not a
   *         robot.
   * @throws PersistenceException if the persistence layer reports an error.
   */
  public RobotAccountData unregister(ParticipantId robotId) throws RobotRegistrationException,
      PersistenceException;

  /**
   * Registers a new robot or re-registers an existing robot in order to update the robot location.
   *
   * @param robotId the robot id.
   * @param location the new location of the robot (URI).
   * @return the updated robot account.
   * @throws RobotRegistrationException if the id to re-register exist but is not a robot.
   * @throws PersistenceException if the persistence layer reports an error.
   */
  public RobotAccountData registerOrUpdate(ParticipantId robotId, String location)
      throws RobotRegistrationException, PersistenceException;

  /** Adds listener. */
  public void addRegistrationListener(Listener listener);

  /** Removes listener. */
  public void removeRegistrationListener(Listener listener);
}