| /******************************************************************************* |
| * Copyright (c) 2007, 2010 IBM Corporation and others. |
| * |
| * This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.pde.api.tools.internal.provisional.model; |
| |
| import org.eclipse.core.runtime.CoreException; |
| import org.eclipse.osgi.service.resolver.ResolverError; |
| import org.eclipse.pde.api.tools.internal.provisional.IApiDescription; |
| import org.eclipse.pde.api.tools.internal.provisional.IApiFilterStore; |
| import org.eclipse.pde.api.tools.internal.provisional.IRequiredComponentDescription; |
| import org.eclipse.pde.api.tools.internal.provisional.descriptors.IElementDescriptor; |
| import org.eclipse.pde.api.tools.internal.search.IReferenceCollection; |
| |
| /** |
| * Describes the API of a software component. An API component is composed of a |
| * set of {@link IApiTypeRoot}s owned by the component and a description |
| * (manifest) of the component's API. |
| * |
| * @since 1.0.0 |
| */ |
| public interface IApiComponent extends IApiTypeContainer { |
| |
| /** |
| * Returns this component's symbolic name. This is a handle-only method - |
| * the component may not exist or may be disposed. |
| * |
| * @return component's symbolic name |
| */ |
| public String getSymbolicName(); |
| |
| /** |
| * Returns this component's API description. |
| * |
| * @return API description for this component |
| * @throws CoreException if there was a problem creating the API description |
| * for this component |
| * @throws CoreException if its baseline is disposed |
| */ |
| public IApiDescription getApiDescription() throws CoreException; |
| |
| /** |
| * Returns whether this component has an underlying API description. Even if |
| * a component has no underlying description it will return one from |
| * {@link #getApiDescription()}, but it will be empty. This method allows |
| * clients to know if there was any thing used to populate the description. |
| * |
| * @return whether this component has an underlying API description |
| */ |
| public boolean hasApiDescription(); |
| |
| /** |
| * Returns this component's version identifier. |
| * |
| * @return component version |
| */ |
| public String getVersion(); |
| |
| /** |
| * Returns the execution environments required by this component for |
| * building and running. An execution environment is represented by a unique |
| * identifier as defined by OSGi - for example "J2SE-1.4" or |
| * "CDC-1.0/Foundation-1.0". Any of the environments will allow this |
| * component to be resolved. |
| * |
| * @return execution environment identifier |
| * @throws CoreException if its baseline is disposed |
| */ |
| public String[] getExecutionEnvironments() throws CoreException; |
| |
| /** |
| * Returns {@link IApiTypeContainer}s containing the {@link IApiTypeRoot}s |
| * associated with this component in the order they would appear on the |
| * build path or class path. |
| * |
| * @return {@link IApiTypeContainer}s |
| */ |
| public IApiTypeContainer[] getApiTypeContainers() throws CoreException; |
| |
| /** |
| * Returns {@link IApiTypeContainer}s containing the {@link IApiTypeRoot}s |
| * associated with this component that comes from the given component id in |
| * the order they would appear on the build path or class path. |
| * |
| * This is used to filter out the {@link IApiTypeContainer}s coming from a |
| * fragment |
| * |
| * @param id the given component id |
| * @return {@link IApiTypeContainer}s |
| * @throws CoreException if its baseline is disposed |
| */ |
| public IApiTypeContainer[] getApiTypeContainers(String id) throws CoreException; |
| |
| /** |
| * Returns a collection of descriptions of components required by this |
| * component or an empty collection if none. |
| * |
| * @return required component descriptions, possibly empty |
| * @throws CoreException if its baseline is disposed |
| */ |
| public IRequiredComponentDescription[] getRequiredComponents() throws CoreException; |
| |
| /** |
| * Returns the location of this API component. |
| * |
| * @return location |
| */ |
| public String getLocation(); |
| |
| /** |
| * Returns if the component is a system component (a JRE definition for |
| * example) or not. System components are not persisted with baselines, as |
| * they are recreated dynamically by the framework |
| * |
| * @return true if the component is a system component, false otherwise |
| */ |
| public boolean isSystemComponent(); |
| |
| /** |
| * Returns if the component is a source component or not. A source component |
| * is not persisted with profiles, as they don't contain any binaries. |
| * |
| * <p> |
| * A component is a source component if and only if one of the following |
| * conditions is true: |
| * </p> |
| * <ul> |
| * <li>its manifest contains an entry called |
| * <code>Eclipse-SourceBundle</code></li> |
| * <li>its <code>plugin.xml</code> file contains an extension for the |
| * extension point if the component is not a fragment. |
| * <li>its <code>fragment.xml</code> file contains an extension for the |
| * extension point if the component is a fragment. |
| * <code>org.eclipse.pde.core.source</code></li> |
| * </ul> |
| * |
| * @return true if the component is a source component, false otherwise |
| * @throws CoreException if its baseline is disposed |
| */ |
| public boolean isSourceComponent() throws CoreException; |
| |
| /** |
| * Disposes this API component. Clients must call this method when done with |
| * an API component. Note that disposing an {@link IApiBaseline} will |
| * dispose all of its components. |
| */ |
| public void dispose(); |
| |
| /** |
| * Returns the {@link IApiBaseline} this component is contained in. |
| * |
| * @return the parent {@link IApiBaseline} |
| * @throws CoreException if its baseline is disposed |
| */ |
| public IApiBaseline getBaseline() throws CoreException; |
| |
| /** |
| * Returns a store of problem filters defined for this component or |
| * <code>null</code> if none. |
| * |
| * @return filter store or <code>null</code> |
| * @throws CoreException if its baseline is disposed |
| */ |
| public IApiFilterStore getFilterStore() throws CoreException; |
| |
| /** |
| * Returns whether this API component is a fragment. |
| * |
| * @return whether this API component is a fragment |
| * @throws CoreException if its baseline is disposed |
| */ |
| public boolean isFragment() throws CoreException; |
| |
| /** |
| * Returns the host {@link IApiComponent} for this component iff this |
| * component is a fragment. Otherwise <code>null</code> is returned. |
| * |
| * @return the host {@link IApiComponent} for this component or |
| * <code>null</code>. |
| * @throws CoreException if the baseline is disposed |
| */ |
| public IApiComponent getHost() throws CoreException; |
| |
| /** |
| * Returns whether this API component is the host of one or more fragments. |
| * |
| * @return whether this API component is the host of one or more fragments |
| * @throws CoreException if its baseline is disposed |
| */ |
| public boolean hasFragments() throws CoreException; |
| |
| /** |
| * Returns the lowest execution environments required by this component for |
| * building and running. An execution environment is represented by a unique |
| * identifier as defined by OSGi - for example "J2SE-1.4" or |
| * "CDC-1.0/Foundation-1.0". |
| * |
| * <p> |
| * The result will be more than one execution environment when the |
| * corresponding api component has a mixed of execution environments in the |
| * JRE family (JRE-1.1, J2SE-1.2,...) and in OSGi minimums or cdc/foundation |
| * families. |
| * </p> |
| * <p> |
| * Since the latter ones are not exact subsets of the ones from the JREs |
| * family, we need to return all the incompatible ones. |
| * </p> |
| * |
| * @return execution environment identifiers |
| * @throws CoreException if its baseline is disposed |
| */ |
| public String[] getLowestEEs() throws CoreException; |
| |
| /** |
| * Returns the list of errors found during the component resolution. |
| * |
| * @return the list of errors or <code>null</code> if none |
| * @throws CoreException if its baseline is disposed |
| */ |
| public ResolverError[] getErrors() throws CoreException; |
| |
| /** |
| * Returns the associated element descriptor for this member. |
| * |
| * @return element descriptor |
| */ |
| public IElementDescriptor getHandle(); |
| |
| /** |
| * Returns all references to this component as registered by API use scans |
| * with the Use Scan Manager. |
| * |
| * @return the collection of reference descriptors |
| */ |
| public IReferenceCollection getExternalDependencies(); |
| |
| /** |
| * @return true if the current component is disposed |
| */ |
| public boolean isDisposed(); |
| } |