/*
 * Copyright (c) 2015 Eike Stepper (Berlin, Germany) and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Eike Stepper - initial API and implementation
 */
package org.eclipse.userstorage;

import org.eclipse.userstorage.internal.StorageServiceRegistry;
import org.eclipse.userstorage.spi.ICredentialsProvider;

import java.net.URI;
import java.util.concurrent.Semaphore;

/**
 * Represents a remote <i>user storage service</i> (USS).
 * <p>
 * The {@link Registry storage service registry} makes known storages available and supports the
 * {@link Registry#addService(String, URI, URI, URI, URI, String) addition} of {@link Dynamic dynamic}
 * storages.
 * <p>
 *
 * @author Eike Stepper
 * @noextend This interface is not intended to be extended by clients.
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IStorageService extends Comparable<IStorageService>
{
  /**
   * Returns the label of the REST service behind this storage.
   *
   * @return the label of the REST service behind this storage, never <code>null</code>.<p>
   */
  public String getServiceLabel();

  /**
   * Returns the URI of the REST service behind this storage.
   * <p>
   * The service URI is a unique identifier of a storage and it is used as the lookup key in
   * {@link Registry#getService(URI) Registry.getStorage()}.
   *
   * @return the URI of the REST service behind this storage, never <code>null</code>.<p>
   */
  public URI getServiceURI();

  /**
   * Returns the create account URI of this storage.
   *
   * @return the create account URI of this storage, can be <code>null</code>.<p>
   */
  public URI getCreateAccountURI();

  /**
   * Returns the edit account URI of this storage.
   *
   * @return the edit account URI of this storage, can be <code>null</code>.<p>
   */
  public URI getEditAccountURI();

  /**
   * Returns the recover password URI of this storage.
   *
   * @return the recover password URI of this storage, can be <code>null</code>.<p>
   */
  public URI getRecoverPasswordURI();

  /**
   * Returns the terms of use link of this storage.
   *
   * @return the terms of use link of this storage, can be <code>null</code>.<p>
   */
  public String getTermsOfUseLink();

  /**
   * Returns a one-permit semaphore that this service acquires while control is passed to a {@link ICredentialsProvider credentials provider},
   * such a a login dialog.
   *
   * @return a one-permit semaphore that this service acquires while control is passed to a {@link ICredentialsProvider credentials provider},
   * such a a login dialog.<p>
   */
  public Semaphore getAuthenticationSemaphore();

  /**
   * A {@link IStorageService storage service} that is dynamically created as opposed to being
   * statically contributed via the <code>org.eclipse.userstorage.storages</code> extension point).
   * <p>
   * Dynamic storages can be created and registered via the {@link Registry#addService(String, URI, URI, URI, URI, String) addStorage()} method
   * and only dynamic storages can be {@link #remove() removed} from the {@link Registry storage service registry}.
   * <p>
   *
   * @author Eike Stepper
   * @noextend This interface is not intended to be extended by clients.
   * @noimplement This interface is not intended to be implemented by clients.
   */
  public interface Dynamic extends IStorageService
  {
    /**
     * Removes this storage from the {@link Registry storage service registry}.
     */
    public void remove();
  }

  /**
   * Provides a central place to access registered {@link IStorageService storage services}.
   * <p>
   * This registry contains storages of the following two types:
   * <p>
   * <ul>
   * <li> Static storages that are contributed via the <code>org.eclipse.userstorage.storages</code> extension point.
   * <li> {@link Dynamic Dynamic} storages that are created via the {@link #addService(String, URI, URI, URI, URI, String) addStorage()} method.
   * </ul>
   * <p>
   * To access the storages in this registry an application uses the {@link #INSTANCE} constant as follows:
   * <p>
   * <pre>   IStorage[] storages = IStorage.Registry.INSTANCE.getStorages();</pre>
   * <p>
   * To access the data that is stored in a storage on the server side an application must create a {@link IStorage storage}.
   * <p>
   *
   * @author Eike Stepper
   * @noextend This interface is not intended to be extended by clients.
   * @noimplement This interface is not intended to be implemented by clients.
   */
  public interface Registry
  {
    /**
     * The singleton instance of this registry.
     */
    public static final Registry INSTANCE = StorageServiceRegistry.INSTANCE;

    /**
     * Returns an array of all currently registered storages.
     *
     * @return an array of all currently registered storages, never <code>null</code>.<p>
     */
    public IStorageService[] getServices();

    /**
     * Returns the currently registered storage for the given <code>serviceURI</code>.
     *
     * @return the currently registered storage for the given <code>serviceURI</code>,
     *         or <code>null</code> if no storage is registered for the given <code>serviceURI</code>.<p>
     */
    public IStorageService getService(URI serviceURI);

    /**
     * Adds a new dynamic storage with the given <code>serviceLabel</code> and the given <code>serviceURI</code> to this registry.
     * <p>
     *
     * @param serviceLabel the label of the REST service behind the storage to be created and registered.
     *        The label <i>must not be</i> <code>null</code> or empty and it <i>should be</i> unique (the latter is not a strict requirement
     *        but rather a recommendation to make it easier for a user to pick a storage for an application). See also {@link IStorageService#getServiceLabel()}.<p>
     * @param serviceURI the base URI of the REST service behind the storage to be created and registered.
     *        The service URI is a unique identifier of the storage and it is used as the lookup key in
     *        {@link Registry#getService(URI) Registry.getStorage()}. It <i>must not be</i> <code>null</code>. See also {@link IStorageService#getServiceURI()}.<p>
     * @param createAccountURI an optional (<i>can be</i> <code>null</code>) URI that a user interface can use to point the user to a web page that supports the creation
     *        of the user account needed for the REST service behind the storage to be created and registered. See also {@link IStorageService#getCreateAccountURI()}.<p>
     * @param editAccountURI an optional (<i>can be</i> <code>null</code>) URI that a user interface can use to point the user to a web page that supports the modification
     *        of the user account needed for the REST service behind the storage to be created and registered. See also {@link IStorageService#getEditAccountURI()}.<p>
     * @param recoverPasswordURI an optional (<i>can be</i> <code>null</code>) URI that a user interface can use to point the user to a web page that supports the recovery
     *        of the password needed to log into the REST service behind the storage to be created and registered. See also {@link IStorageService#getRecoverPasswordURI()}.<p>
     * @param termsOfUseLink an optional (<i>can be</i> <code>null</code>) string that a user interface can use to point the user to a web page that supports the terms of use
     *        of the REST service behind the storage. See also {@link IStorageService#getTermsOfUseLink()}.<p>
     *
     * @return the newly created and registered storage, never <code>null</code>.<p>
     * @throws IllegalStateException if a storage with the same <code>serviceURI</code> is already registered in this registry.<p>
     *
     * @see #addService(String, URI)
     */
    public IStorageService.Dynamic addService(String serviceLabel, URI serviceURI, URI createAccountURI, URI editAccountURI, URI recoverPasswordURI,
        String termsOfUseLink) throws IllegalStateException;

    /**
     * Adds a new dynamic storage with the given <code>serviceLabel</code> and the given <code>serviceURI</code> to this registry.
     * <p>
     * Calling this method is identical to calling <code>addStorage(serviceLabel, serviceURI, null, null, null)</code>.
     * <p>
     *
     * @param serviceLabel the label of the REST service behind the storage to be created and registered.
     *        The label <i>must not be</i> <code>null</code> or empty and it <i>should be</i> unique (the latter is not a strict requirement
     *        but rather a recommendation to make it easier for a user to pick a storage for an application). See also {@link IStorageService#getServiceLabel()}.<p>
     * @param serviceURI the base URI of the REST service behind the storage to be created and registered.
     *        The service URI is a unique identifier of the storage and it is used as the lookup key in
     *        {@link Registry#getService(URI) Registry.getStorage()}. It <i>must not be</i> <code>null</code>. See also {@link IStorageService#getServiceURI()}.<p>
     *
     * @return the newly created and registered storage, never <code>null</code>.<p>
     * @throws IllegalStateException if a storage with the same <code>serviceURI</code> is already registered in this registry.<p>
     *
     * @see #addService(String, URI, URI, URI, URI, String)
     */
    public IStorageService.Dynamic addService(String serviceLabel, URI serviceURI) throws IllegalStateException;

    /**
     * Refreshes the dynamic services from the underlying secure storage and returns the newly added services.
     *
     * @return the newly added services.<p>
     */
    public IStorageService.Dynamic[] refresh();

    /**
     * Adds the given listener to the list of listeners that are notified about changes in this registry.
     *
     * @param listener the listener to add to the list of listeners that are notified about changes in this registry.
     */
    public void addListener(Listener listener);

    /**
     * Removes the given listener from the list of listeners that are notified about changes in this registry.
     *
     * @param listener the listener to remove from the list of listeners that are notified about changes in this registry.
     */
    public void removeListener(Listener listener);

    /**
     * Listens to changes in the {@link Registry#INSTANCE storage service registry}.
     *
     * @author Eike Stepper
     */
    public interface Listener
    {
      /**
       * Called when a service has been added to the {@link Registry#INSTANCE storage service registry}.
       *
       * @param service the service that has been added to the registry, never <code>null</code>.
       */
      public void serviceAdded(IStorageService service);

      /**
       * Called when a service has been removed from the {@link Registry#INSTANCE storage service registry}.
       *
       * @param service the service that has been removed from the registry, never <code>null</code>.
       */
      public void serviceRemoved(IStorageService service);
    }
  }
}