/*******************************************************************************
 * Copyright (c) 2009 Markus Alexander Kuppe.
 * 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:
 *     Markus Alexander Kuppe (ecf-dev_eclipse.org <at> lemmster <dot> de) - initial API and implementation
 *******************************************************************************/

package org.eclipse.ecf.discovery;

import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.ecf.core.identity.Namespace;
import org.eclipse.ecf.discovery.identity.IServiceID;
import org.eclipse.ecf.discovery.identity.IServiceTypeID;
import org.eclipse.equinox.concurrent.future.IFuture;

/**
 * Entry point discovery locator. This interface exposes the ability to
 * add/remove listeners for newly discovered services and service types, and get
 * (synch) and request (asynchronous) service info from a remote service
 * provider.
 * <p>
 * This interface can be used by container provider implementations as an
 * adapter so that calls to IContainer.getAdapter(IDiscoveryLocator.class) will
 * return a non-null instance of a class that implements this interface. Clients
 * can then proceed to use this interface to interact with the given discovery
 * implementation.
 * 
 * @since 3.0
 */
public interface IDiscoveryLocator extends IAdaptable {
	/**
	 * The name of the discovery container under which it is registered with the
	 * OSGi runtime as a service property
	 */
	public static final String CONTAINER_NAME = "org.eclipse.ecf.discovery.containerName"; //$NON-NLS-1$

	/**
	 * Synchronously retrieve info about the service
	 * 
	 * @param aServiceID
	 *            IServiceID of the service to get info about. Must not be
	 *            <code>null</code>.
	 * @return IServiceInfo the service info retrieved. <code>null</code> if no
	 *         information retrievable.
	 */
	public IServiceInfo getServiceInfo(IServiceID aServiceID);

	/**
	 * Synchronously get service info about all known services
	 * 
	 * @return IServiceInfo[] the resulting array of service info instances.
	 *         Will not be <code>null</code>. May be of length 0.
	 */
	public IServiceInfo[] getServices();

	/**
	 * Synchronously get service info about all known services of given service
	 * type
	 * 
	 * @param aServiceTypeID
	 *            IServiceTypeID defining the type of service we are interested
	 *            in getting service info about. Must not be <code>null</code>
	 * @return IServiceInfo[] the resulting array of service info instances.
	 *         Will not be <code>null</code>. May be of length 0.
	 */
	public IServiceInfo[] getServices(IServiceTypeID aServiceTypeID);

	/**
	 * Synchronously get service info about all known services of given service
	 * type
	 * 
	 * @return IServiceTypeID[] the resulting array of service type IDs. Will
	 *         not be <code>null</code>. May be of length 0.
	 */
	public IServiceTypeID[] getServiceTypes();

	/**
	 * Get a Namespace for services associated with this discovery container
	 * adapter. The given Namespace may be used via IServiceIDFactory to create
	 * IServiceIDs rather than simple IDs. For example:
	 * 
	 * <pre>
	 * IServiceID serviceID = ServiceIDFactory.getDefault().createServiceID(container.getServicesNamespace(),
	 * 		serviceType, serviceName);
	 * </pre>
	 * 
	 * @return Namespace for creating service IDs. Will not be <code>null</code>
	 *         .
	 */
	public Namespace getServicesNamespace();

	/**
	 * Purges the underlying IServiceInfo cache if available in the current
	 * provider
	 * 
	 * @return The previous cache content
	 */
	public IServiceInfo[] purgeCache();

	/* Listener related API */

	/**
	 * Add a service listener. The given listener will have its method called
	 * when a service is discovered.
	 * 
	 * @param listener
	 *            IServiceListener to be notified. Must not be <code>null</code>
	 *            .
	 */
	public void addServiceListener(IServiceListener listener);

	/**
	 * Add a service listener. The given listener will have its method called
	 * when a service with a type matching that specified by the first parameter
	 * is discovered.
	 * 
	 * @param type
	 *            String type to listen for. Must not be <code>null</code>. Must
	 *            be formatted according to this specific IDiscoveryContainer
	 * @param listener
	 *            IServiceListener to be notified. Must not be <code>null</code>
	 *            .
	 */
	public void addServiceListener(IServiceTypeID type, IServiceListener listener);

	/**
	 * Add a service type listener. The given listener will have its method
	 * called when a service type is discovered.
	 * 
	 * @param listener
	 *            the listener to be notified. Must not be <code>null</code>.
	 */
	public void addServiceTypeListener(IServiceTypeListener listener);

	/**
	 * Remove a service listener. Remove the listener from this container
	 * 
	 * @param listener
	 *            IServiceListener listener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceListener(IServiceListener listener);

	/**
	 * Remove a service listener. Remove the listener associated with the type
	 * specified by the first parameter.
	 * 
	 * @param type
	 *            String of the desired type to remove the listener. Must not be
	 *            <code>null</code>. Must be formatted according to this
	 *            specific IDiscoveryContainer
	 * @param listener
	 *            IServiceListener listener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceListener(IServiceTypeID type, IServiceListener listener);

	/**
	 * Remove a service type listener. Remove the type listener.
	 * 
	 * @param listener
	 *            IServiceTypeListener to be removed. Must not be
	 *            <code>null</code>.
	 */
	public void removeServiceTypeListener(IServiceTypeListener listener);

	/* Future related API */

	/**
	 * Asynchronously retrieve info about the service
	 * 
	 * @param aServiceID
	 *            IServiceID of the service to get info about. Must not be
	 *            <code>null</code>.
	 * @return IFuture a future status wrapping an IServiceInfo or
	 *         <code>null</code> if no information retrievable.
	 */
	public IFuture getAsyncServiceInfo(IServiceID aServiceID);

	/**
	 * Asynchronously get service info about all known services
	 * 
	 * @return IFuture wrapping an IServiceTypeID[]. The resulting array of
	 *         service type IDs will not be <code>null</code>. May be of length
	 *         0.
	 */
	public IFuture getAsyncServices();

	/**
	 * Asynchronously get service info about all known services of given service
	 * type
	 * 
	 * @param aServiceTypeID
	 *            IServiceTypeID defining the type of service we are interested
	 *            in getting service info about. Must not be <code>null</code>
	 * @return IFuture wrapping an IServiceTypeID[]. The resulting array of
	 *         service type IDs will not be <code>null</code>. May be of length
	 *         0.
	 */
	public IFuture getAsyncServices(IServiceTypeID aServiceTypeID);

	/**
	 * Asynchronously get service info about all known services of given service
	 * type
	 * 
	 * @return IFuture wrapping an IServiceTypeID[]. The resulting array of
	 *         service type IDs will not be <code>null</code>. May be of length
	 *         0.
	 */
	public IFuture getAsyncServiceTypes();
}