package query.hessian.accounts;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import replicationAnnotations.OuterWorldAPI;

/**
 * 3rd version of account service provides more information about accounts.
 *
 * @author andrey.kuprishov
 */
@OuterWorldAPI
public interface AccountService3 extends AccountService2 {
  @NotNull
  String SERVICE_CODE = "AccountService";

  /**
   * Gets action information about previously given item. Method repeats method
   * {@link AccountService#getGivenAvatarItem(long)} but has additional parameter allowing
   * to distinguish slave gametool for certain shard where the invokation will be
   * forwarded from master gametool.
   *
   * @param shardTitle  name of interested shard
   * @param itemActionId  id of action that was in GiveItemResult returned by giveItemToAvatar
   * @return information about item action, or null if action not found
   * @see ItemActionInfo
   * @see AccountService#getGivenAvatarItem(long)
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   */
  @Nullable
  ItemActionInfo getGivenAvatarItemOnShard(@NotNull String shardTitle, long itemActionId) throws AccountServiceException;

  /**
   * Cancels pending action that was created to give item to avatar. Method repeats method
   * {@link AccountService#cancelPendingAvatarItem(long)} but has additional parameter allowing
   * to distinguish slave gametool for certain shard where the invokation will be forwarded
   * from master gametool.
   *
   * @param shardTitle  name of interested shard
   * @param itemActionId  id of action that was returned from giveItemToAvatar.
   * @return  result of cancellation: cancelled, or action not found, or action is not pending).
   * @throws AccountServiceException when internal GameTool error occures (e.g. DB unavailable).
   * @see CancelItemResult
   * @see AccountService#cancelPendingAvatarItem(long)
   */
  @NotNull
  CancelItemResult cancelPendingAvatarItemOnShard(@NotNull String shardTitle, long itemActionId) throws AccountServiceException;
}