// Copyright (c) 2009 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

package org.chromium.sdk.internal;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;

/**
 * Manager that switches on and off some resource for a shared multiuser access.
 * The nature of actual resource should be defined in subclass of
 * {@link SessionManager}. Time period when resource is on is called "session".
 * Switch on operation (aka session creation) must be an atomic operation.
 * Switch off (aka session closing) may be lengthy asynchronous operation.
 * <p>
 * If no user needs it, manager switches the resource off. On the first demand
 * resource gets switched on (and new session gets created). After the last user
 * has released the resource, the session finishes either instantly or
 * some time later. In the latter case resource becomes temporary unavailable.
 * The manager does not operate resource in any other sense than switching it
 * on and off.
 * <p>
 * Every user first acquires the resource by calling {@link #connect()} method.
 * It gets ticket which points to the corresponding session. Method
 * {@link Ticket#dismiss()} must be called when resource is no more needed.
 * @param <SESSION> user class that represents a session; must
 *                  extend {@link SessionBase}
 * @param <EX> exception that is allowed to be thrown when resource is being switched
 *             on and the new session is starting; {@link RuntimeException}
 *             is a good default parameter value
 */
public abstract class SessionManager<SESSION extends SessionManager.SessionBase<SESSION>,
    EX extends Exception> {

  // Holds current session; all access must be synchronized on "this".
  private SESSION currentSession = null;

  /**
   * Ticket to resource use. Every client gets its own copy. All tickets must
   * be dismissed in order for resource to be switched off.
   * @param <SESSION> is be the same type as of manager that issued this ticket
   */
  public interface Ticket<SESSION> {
    /**
     * Each valid ticket points to session of the resource. The actual type
     * {@code SESSION} is provided by user (as a type parameter of enclosing
     * SessionManager). The actual resource should be accessible from
     * {@code SESSION}.
     * @return non-null current session
     * @throws IllegalStateException if ticket is no longer valid
     */
    SESSION getSession();

    /**
     * Releases resource and makes ticket invalid. Switches the resource
     * off if it was a last ticket.
     * @throws IllegalStateException if ticket is no more valid
     */
    void dismiss();
  }

  /**
   * Registers user request for resource and switches the resource on if required.
   * @return new ticket which symbolize use of resource until
   *             {@link Ticket#dismiss()} is called
   * @throws EX if connect required creating a new session and if the new session creation
   *         has failed
   */
  public Ticket<SESSION> connect() throws EX {
    synchronized (this) {
      if (currentSession != null) {
        // this may reset currentSession
        currentSession.checkHealth();
      }
      if (currentSession == null) {
        currentSession = newSessionObject();
        if (currentSession.manager != this) {
          throw new IllegalArgumentException("Wrong manager was set in session");
        }
      }
      return currentSession.newTicket();
    }
  }

  /**
   * User-provided constructor of a new session. It should switch the resource on
   * whatever it actually means.
   * @return new instance of resource use session
   * @throws EX if switching resource on or creating a new session failed
   */
  protected abstract SESSION newSessionObject() throws EX;

  /**
   * Base class for user session. It should be subclassed and it is parameterized by
   * this subclass. Object construction should have semantics of switching resource
   * on. It gets constructed via user-defined {@link SessionManager#newSessionObject()}.
   * Subclass should honestly pass instance of {@link SessionManager} to the base
   * class. User also should implement {@link #lastTicketDismissed()} and helper
   * {@link #getThisAsSession()}.
   * @param <SESSION> the very user class which extends {@link SessionBase};
   *                  {@link #getThisAsSession()} should compile as "return this;"
   */
  public static abstract class SessionBase<SESSION extends SessionBase<SESSION>> {
    private final SessionManager<?, ?> manager;
    private boolean isConnectionStopped = false;
    private boolean isCancelled = false;

    SessionBase(SessionManager<SESSION, ?> manager) {
      this.manager = manager;
    }

    /**
     * Must be simply "return this;"
     */
    protected abstract SESSION getThisAsSession();

    /**
     * Session may check its health here. This check is made on
     * every new connection. If it appears that the session is no longer alive
     * the method should call {@link #interruptSession()}. However, this is a highly
     * unwanted scenario: session should interrupt itself synchronously, no
     * on-demand from this method.
     */
    protected abstract void checkHealth();

    /**
     * User-provided behavior when no more valid tickets left. Resource should
     * be switched off whatever it actually means and the session closed.
     * There are 3 options here:
     * <ol>
     * <li>Method is finished with {@link #closeSession()} call. Method
     * {@link SessionManager#connect()} does not interrupt its service and simply
     * creates new session the next call.
     * <li>Method is finished with {@link #stopNewConnections()} call. Connection
     * process is put on hold after this and {@link SessionManager#connect()} starts
     * to throw {@link IllegalStateException}. Later {@link #closeSession()} must
     * be called possibly asynchronously. After this the resource is available again
     * and a new session may be created.
     * <li>Do not call any of methods listed above. This probably works but is
     * not specified here.
     * </ol>
     */
    protected abstract void lastTicketDismissed();

    /**
     * See {@link #lastTicketDismissed()}. This method is supposed to be called
     * from there, but not necessarily.
     */
    protected void stopNewConnections() {
      synchronized (manager) {
        isConnectionStopped = true;
      }
    }

    /**
     * Stops all new connections and cancels all existing tickets. Don't forget
     * to call {@link #closeSession()} manually.
     * @return collection of exceptions we gathered from tickets
     */
    protected Collection<? extends RuntimeException> interruptSession() {
      synchronized (manager) {
        isConnectionStopped = true;
        isCancelled = true;
        // TODO(peter.rybin): notify listeners here in case they are interested
        tickets.clear();
      }

      return Collections.emptyList();
    }

    /**
     * See {@link #lastTicketDismissed()}. This method is supposed to be called
     * from there, but not necessarily.
     */
    protected void closeSession() {
      synchronized (manager) {
        isConnectionStopped = true;
        if (!tickets.isEmpty()) {
          throw new IllegalStateException("Some tickets are still valid");
        }
        if (manager.currentSession != this) {
          throw new IllegalStateException("Session is not active");
        }
        manager.currentSession = null;
      }
    }

    /**
     * Creates new ticket that is to be dismissed later.
     * Internal method. However user may use it or even make it public.
     */
    protected Ticket<SESSION> newTicket() {
      synchronized (manager) {
        if (isConnectionStopped) {
          throw new IllegalStateException("Connection has been stopped");
        }
        TicketImpl ticketImpl = new TicketImpl();
        tickets.add(ticketImpl);
        return ticketImpl;
      }
    }

    private final List<TicketImpl> tickets = new ArrayList<TicketImpl>();

    private class TicketImpl implements Ticket<SESSION> {
      private volatile boolean isDismissed = false;

      public void dismiss() {
        synchronized (manager) {
          if (!isCancelled) {
            boolean res = tickets.remove(this);
            if (!res) {
              throw new IllegalStateException("Ticket is already dismissed");
            }
            if (tickets.isEmpty()) {
              lastTicketDismissed();
            }
          }
          isDismissed = true;
        }
      }

      public SESSION getSession() {
        if (isDismissed) {
          throw new IllegalStateException("Ticket is dismissed");
        }
        return getThisAsSession();
      }
    }
  }

  /**
   * This method is completely unsynchronized. Is should be used for
   * single-threaded tests only.
   */
  public SESSION getCurrentSessionForTest() {
    return currentSession;
  }
}