/**
 * ITitleProvider.java
 * Created May 14, 2008
 * Copyright (c) TANDBERG Television 2007-2008
 */
package com.tandbergtv.watchpoint.pmm.title.provider;

import java.util.Collection;

import com.tandbergtv.watchpoint.pmm.entities.Title;

/**
 * Provides a way to browse a collection of titles in a library. The provider contains one or more
 * instances of a certain type of library, e.g. Xport Packager, MediaModeler, AMS, filesystem etc.
 * 
 * Each provider has a systemId which is globally unique.
 * 
 * @author Sahil Verma
 */
public interface ITitleProvider {
	
	/**
	 * Returns the title provider id. This is equivalent to the concept of a systemId that is also
	 * currently used by resource types.
	 * 
	 * @return
	 */
	String getSystemID();
	
	/**
	 * Returns the name of the provider
	 * 
	 * @return
	 */
	String getName();
	
	/**
	 * Returns the list of metadata specification formats that the provider supports
	 * 
	 * @return
	 */
	Collection<String> getSupportedSpecifications();
	
	/**
	 * Determines whether this provider can support the specified metadata format
	 * 
	 * @param specification
	 * @return
	 */
	boolean supportsSpecification(String specification);
	
	/**
	 * Returns the class that performs a search of titles using arbitrary criteria
	 * 
	 * @return
	 */
	ITitleSearchStrategy getSearchStrategy();

	/**
	 * Returns the collection of provider instances
	 * 
	 * @return A Collection of Title Provider Instances 
	 */
	Collection<ITitleProviderInstance> getProviderInstances();

	/**
	 * Returns the Provider Instance given the Provider Instance Key
	 * 
	 * @param key The Provider Instance Key
	 * @return The Title Provider Instance
	 */
	ITitleProviderInstance getProviderInstance(String key);
	
	/**
	 * Returns the URL of a particular instance of the title provider. The key must be of the form
	 * systemid-instanceid. The return value will be of the form host or host:port or an SMTP address. 
	 * 
	 * @param key
	 * @return
	 */
	String getProviderInstanceURL(String key);
	
	/**
	 * Returns the URL that allows navigation to the specified Title. This could be an HTTP URL,
	 * a filesystem location etc. Note that not all providers will support this feature, some
	 * might provide a URL to the application and locating the title will have to be done manually.
	 * 
	 * @param title
	 * @return
	 */
	String getTitleDisplayURL(Title title);
}