/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/**

 * 

 */

package com.nokia.sdt.component;

import com.nokia.cpp.internal.api.utils.core.MessageLocation;

import org.eclipse.core.runtime.IAdaptable;

import org.osgi.framework.Bundle;

import org.osgi.framework.Version;

import java.io.*;

/** 

 * The main interface for a component.

 * Each aspect of component information and behavior

 * is implemented by one or more adapters. Adapters

 * are obtained from each component's provider. 

 * <p>

 * This approach allows the provider to specify how adapters

 * are implemented for the components in provides.

 * <p>

 * The set of adapters can be extended by getting

 * component provider from the component system

 * and registering new adapter factories.

 * <p>

 * Here's an example of obtaining an adapter:

 * <pre>

 * IComponent myComponent = ...

 * IPropertyDescriptorProvider pdProvider =

 *     myComponent.getAdapter(IPropertyDescriptorProvider.class);

 * </pre>

 */

public interface IComponent extends IAdaptable {

	/**

	 * Returns the provider that implements this component type

	 */

	IComponentProvider getProvider();

	/**

	 * Returns the bundle providing this component (may be null)

	 */

	Bundle getBundle();

    /** 

     * Returns the component's unique id. The convention

     * for component naming is specific to a provider, but

     * each id must be unique to the provider.

     */

    String getId();

	/**

	 * Returns the component's category, if any.

	 * The result should be already localized, if possible.

	 */

	String getCategory();

	/**

	 * Returns the component's version as an OSGI version object.

	 * @return

	 */

	public Version getComponentVersion();

	/**

	 * Returns a string used as the root part of a

	 * component instance name. This root can have a prefix

	 * and suffix added for uniqueness and source generation purposes.

	 * This method should just return a base name that makes sense

	 * for the component without regard to uniqueness or source

	 * generation issues.

	 */

	String getInstanceNameRoot();

	/**

	 * Returns the "friendly name" attribute of the component.

	 * @return friendly name String

	 */

	String getFriendlyName();

	/**

	 * Returns the base component's unique id, or null if no base component

	 */

	String getBaseComponentId();

	/**

     * Returns the immediate base component for this component.

     */

    IComponent getComponentBase();

    /**

     * An abstract component can act as a base component but cannot be instantiated

     */

    boolean isAbstract();

    /**

     * Returns the component set this component belongs to.

     * Each component is shallow-copied into a component set.

     * @returns IComponentSet or null if this component comes straight

     * from a component provider.   

     */

    IComponentSet getComponentSet();

    /**

     * Create a message location based on this component,

     * e.g. for reporting errors that come from a component definition.

     */

    MessageLocation createMessageLocation();

    /**

     * Get the base directory of the component.

     * May return null if component is not located on disk.

     */

    File getBaseDirectory();

}