org.eclipse.pde.build

## Interface IFetchFactory

    public interface IFetchFactory

Interface to be implemented by clients of the `org.eclipse.pde.build.fetchFactories` extension-point.

The factories are being used at various points in the execution of the PDE Build `eclipse.fetch` Ant task. Based on a map file entry, they are responsible for generating segments of an ant script whose execution will fetch plug-ins, fragments, bundles and features or individual files contained in one of those elements. The format of a map file entry is: `<elementType>@<elementName> = <repositoryTag>, <repositoryDetails>` The format of `elementType` and `elementName` is fixed. The factories specify the value of `repositoryTag` and the format of the `repositoryDetails`. `repositoryTag` and `repositoryDetails` becomes defacto APIs. `repositoryTag` should match the factory id used when declaring the factory extension. For example, for the CVS the value is "CVS". `repositoryDetails` should contains enough details to allow the factory to generate a fetch script retrieving the element.

The fetch factories are being contributed through the `org.eclipse.pde.build.fetchFactories` extension-points.

Fetch factories will not be re-used between different PDE Build `eclipse.fetch` Ant tasks. Each task will create at most one fetch factory instance for the duration of the task processing. This allows implementors to build and maintain stateful information. Such information must be released in `addTargets(IAntScript)` call.

Since:
  3.2

### Field Summary

Fields
`static String` `ELEMENT_TYPE_BUNDLE` One of the value for element type.
`static String` `ELEMENT_TYPE_FEATURE` One of the value for element type.
`static String` `ELEMENT_TYPE_FRAGMENT` One of the value for element type.
`static String` `ELEMENT_TYPE_PLUGIN` One of the value for element type.
`static String` `KEY_ELEMENT_NAME` Key used to store the value of the element name.
`static String` `KEY_ELEMENT_TAG` Key used to store the value of the tag that will be used to fetch the element.
`static String` `KEY_ELEMENT_TYPE` Key used to store the value of the element type

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `addTargets(IAntScript script)` This methods give opportunities to the factory to generate target declaration or other Ant top level constructs in the script.
`void` `generateRetrieveElementCall(Map<String,Object> entryInfos, IPath destination, IAntScript script)` Generates a segment of ant script whose execution will fetch the element (bundle, plug-in, fragment, feature) indicated in the entryInfos arguments.
`void` `generateRetrieveFilesCall(Map<String,Object> entryInfos, IPath destination, String[] files, IAntScript script)` Generates a segment of ant script whose execution will fetch the specified file from the given element.
`void` `parseMapFileEntry(String rawEntry, Properties overrideTags, Map<String,Object> entryInfos)` This method should parse / validate a mapfile entry and derive a corresponding key / value pair structure containing the relevant information.

### Field Detail

#### KEY_ELEMENT_NAME

    static final String KEY_ELEMENT_NAME

Key used to store the value of the element name.

See Also:
  Constant Field Values

#### KEY_ELEMENT_TYPE

    static final String KEY_ELEMENT_TYPE

Key used to store the value of the element type

See Also:
  Constant Field Values

#### KEY_ELEMENT_TAG

    static final String KEY_ELEMENT_TAG

Key used to store the value of the tag that will be used to fetch the element.

The grammar of the expected value is limited to:

             value::= (alpha|digit|'_'|'-')+
          digit ::= [0..9]
          alpha ::= [a..zA..Z]

See Also:
  Constant Field Values

#### ELEMENT_TYPE_BUNDLE

    static final String ELEMENT_TYPE_BUNDLE

One of the value for element type. See `KEY_ELEMENT_TYPE`.

See Also:
  Constant Field Values

#### ELEMENT_TYPE_FEATURE

    static final String ELEMENT_TYPE_FEATURE

One of the value for element type. See `KEY_ELEMENT_TYPE`.

See Also:
  Constant Field Values

#### ELEMENT_TYPE_FRAGMENT

    static final String ELEMENT_TYPE_FRAGMENT

One of the value for element type. See `KEY_ELEMENT_TYPE`.

See Also:
  Constant Field Values

#### ELEMENT_TYPE_PLUGIN

    static final String ELEMENT_TYPE_PLUGIN

One of the value for element type. See `KEY_ELEMENT_TYPE`.

See Also:
  Constant Field Values

### Method Detail

#### parseMapFileEntry

    void parseMapFileEntry(String rawEntry,
                           Properties overrideTags,
                           Map<String,Object> entryInfos)
                    throws CoreException

This method should parse / validate a mapfile entry and derive a corresponding key / value pair structure containing the relevant information.

The arguments specified in the map file are provided. The map with entry infos should be filled with provider specific information that is required in later processing to sucessfully generate the fetch script.

Since 3.6, factories may optionally set the `Constants.KEY_SOURCE_REFERENCES` property in the entry infos map to support the inclusion of source references in the bundle manifest using the Eclipse-SourceReferences header.

Parameters:
  `rawEntry` - the arguments as specified in the map file (may not be `null`).
  `overrideTags` - a key / value containing all the override tags specified for all the repository (maybe `null` or empty). The values of this map of this are read from the fetchTag property (see file scripts/templates/headless-build/build.properties).
  `entryInfos` - the map to store repository specific information derived from the rawEntry.This object is being passed as arguments to the other methods of the factory. The factories are also expected to set `KEY_ELEMENT_TAG` to indicate the tag that will be used to fetch the element. This value is for example used to generate the "qualifier" value of a version number. Note that `KEY_ELEMENT_NAME` and `KEY_ELEMENT_TYPE` are reserved entries whose values respectively refer to the name of the element being fetched and its type.
Throws:
  `CoreException` - if the rawEntry is incorrect.

#### generateRetrieveElementCall

    void generateRetrieveElementCall(Map<String,Object> entryInfos,
                                     IPath destination,
                                     IAntScript script)

Generates a segment of ant script whose execution will fetch the element (bundle, plug-in, fragment, feature) indicated in the entryInfos arguments.

Parameters:
  `entryInfos` - the map that has been built in the `parseMapFileEntry(String, Properties, Map)` method. This map contains the name and the type of the element (resp. `KEY_ELEMENT_NAME` and `KEY_ELEMENT_TYPE`) to put in the destination.
  `destination` - the destination where the element should be fetched to. For example, for a plug-in the `plugin.xml` file is expected to be in `destination/plugin.xml`.
  `script` - the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.

#### generateRetrieveFilesCall

    void generateRetrieveFilesCall(Map<String,Object> entryInfos,
                                   IPath destination,
                                   String[] files,
                                   IAntScript script)

Generates a segment of ant script whose execution will fetch the specified file from the given element.

Parameters:
  `entryInfos` - the map that has been built in the `parseMapFileEntry(String, Properties, Map)` method. This map contains the name and the type of the element (resp. `KEY_ELEMENT_NAME` and `KEY_ELEMENT_TYPE`) to put in the destination.
  `destination` - the destination where the element should be fetched to. For example, for a plug-in the `plugin.xml` file is expected to be in `destination/plugin.xml`.
  `files` - the files to obtained for the specified element.
  `script` - the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.

#### addTargets

    void addTargets(IAntScript script)

This methods give opportunities to the factory to generate target declaration or other Ant top level constructs in the script. The generated elements can be invoked from the ant scripts segments created in `generateRetrieveElementCall(Map, IPath, IAntScript)` and `generateRetrieveFilesCall(Map, IPath, String[], IAntScript)`.