001: /**********************************************************************
002: * Copyright (c) 2004, 2006 Eclipse Foundation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * Gunnar Wagenknecht - Initial API and implementation
010: * IBM Corporation - Initial API and implementation
011: **********************************************************************/package org.eclipse.pde.build;
012:
013: import java.util.Map;
014: import java.util.Properties;
015: import org.eclipse.core.runtime.CoreException;
016: import org.eclipse.core.runtime.IPath;
017:
018: /**
019: * Interface to be implemented by clients of the <code>org.eclipse.pde.build.fetchFactories</code> extension-point.
020: * <p>
021: * The factories are being used at various points in the execution of the PDE Build<code>eclipse.fetch</code> Ant task.
022: * Based on a map file entry, they are responsible for generating segments of an ant script whose execution will fetch
023: * plug-ins, fragments, bundles and features or individual files contained in one of those elements.
024: * The format of a map file entry is:
025: * <code>
026: * <elementType>@<elementName> = <repositoryTag>, <repositoryDetails>
027: * </code>
028: * The format of <code>elementType</code> and <code>elementName</code> is fixed.
029: * The factories specify the value of <code>repositoryTag</code> and the format of the <code>repositoryDetails</code>.
030: * <code>repositoryTag</code> and <code>repositoryDetails</code> becomes defacto APIs.
031: * </br>
032: * <code>repositoryTag</code> should match the factory id used when declaring the factory extension. For example, for the CVS the value is "CVS".
033: * <code>repositoryDetails</code> should contains enough details to allow the factory to generate a fetch script retrieving the element.
034: * </p>
035: * <p>
036: * The fetch factories are being contributed through the <code>org.eclipse.pde.build.fetchFactories</code>
037: * extension-points.
038: * </p>
039: * @since 3.2
040: */
041: public interface IFetchFactory {
042: /** Key used to store the value of the element name. */
043: public static final String KEY_ELEMENT_NAME = "element"; //$NON-NLS-1$
044:
045: /** Key used to store the value of the element type */
046: public static final String KEY_ELEMENT_TYPE = "type"; //$NON-NLS-1$
047:
048: /** Key used to store the value of the tag that will be used to fetch the element.
049: * <p>
050: * The grammar of the expected value is limited to:
051: * <pre>
052: * value::= (alpha|digit|'_'|'-')+
053: * digit ::= [0..9]
054: * alpha ::= [a..zA..Z]
055: * </pre>
056: * */
057: public static final String KEY_ELEMENT_TAG = "tag"; //$NON-NLS-1$
058:
059: /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
060: public static final String ELEMENT_TYPE_BUNDLE = "bundle"; //$NON-NLS-1$
061:
062: /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
063: public static final String ELEMENT_TYPE_FEATURE = "feature"; //$NON-NLS-1$
064:
065: /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
066: public static final String ELEMENT_TYPE_FRAGMENT = "fragment"; //$NON-NLS-1$
067:
068: /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
069: public static final String ELEMENT_TYPE_PLUGIN = "plugin"; //$NON-NLS-1$
070:
071: /**
072: * This method should parse / validate a mapfile entry and derive a corresponding
073: * key / value pair structure containing the relevant information.
074: * <p>
075: * The arguments specified in the map file are provided. The map with entry
076: * infos should be filled with provider specific information that is
077: * required in later processing to sucessfully generate the fetch script.
078: * </p>
079: *
080: * @param rawEntry the arguments as specified in the map file (may not be <code>null</code>).
081: * @param overrideTags a key / value containing all the override tags specified for all the repository (maybe <code>null</code> or empty).
082: * The values of this map of this are read from the fetchTag property (see file scripts/templates/headless-build/build.properties).
083: * @param entryInfos the map to store repository specific information derived from the rawEntry.This object is being passed as arguments to
084: * the other methods of the factory. The factories are also expected to set {@link #KEY_ELEMENT_TAG} to indicate the tag that will be used
085: * to fetch the element. This value is for example used to generate the "qualifier" value of a version number.
086: * Note that {@link #KEY_ELEMENT_NAME} and {@link #KEY_ELEMENT_TYPE} are reserved entries whose values respectively
087: * refer to the name of the element being fetched and its type.
088: * @throws CoreException if the rawEntry is incorrect.
089: */
090: public void parseMapFileEntry(String rawEntry,
091: Properties overrideTags, Map entryInfos)
092: throws CoreException;
093:
094: /**
095: * Generates a segment of ant script whose execution will fetch the element (bundle, plug-in, fragment, feature) indicated in the entryInfos arguments.
096: * <p>
097: * @param entryInfos the map that has been built in the {@link #parseMapFileEntry(String, Properties, Map)} method.
098: * This map contains the name and the type of the element (resp. {@link #KEY_ELEMENT_NAME} and {@link #KEY_ELEMENT_TYPE}) to put in the destination.
099: * @param destination the destination where the element should be fetched to. For example, for a plug-in the <code>plugin.xml</code> file is expected
100: * to be in <code>destination/plugin.xml</code>.
101: * @param script the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.
102: */
103: public void generateRetrieveElementCall(Map entryInfos,
104: IPath destination, IAntScript script);
105:
106: /**
107: * Generates a segment of ant script whose execution will fetch the specified file from the given element.
108: * <p>
109: * @param entryInfos the map that has been built in the {@link #parseMapFileEntry(String, Properties, Map)} method.
110: * This map contains the name and the type of the element (resp. {@link #KEY_ELEMENT_NAME} and {@link #KEY_ELEMENT_TYPE}) to put in the destination.
111: * @param destination the destination where the element should be fetched to. For example, for a plug-in the <code>plugin.xml</code> file is expected
112: * to be in <code>destination/plugin.xml</code>.
113: * @param files the files to obtained for the specified element.
114: * @param script the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.
115: */
116: public void generateRetrieveFilesCall(Map entryInfos,
117: IPath destination, String[] files, IAntScript script);
118:
119: /**
120: * This methods give opportunities to the factory to generate target declaration or other Ant top level constructs in the script.
121: * The generated elements can be invoked from the ant scripts segments created in {@link #generateRetrieveElementCall(Map, IPath, IAntScript)}
122: * and {@link #generateRetrieveFilesCall(Map, IPath, String[], IAntScript)}.
123: */
124: public void addTargets(IAntScript script);
125: }
|