IFetchFactory


1   /**********************************************************************
2    * Copyright (c) 2004, 2006 Eclipse Foundation and others.
3    * All rights reserved.   This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     Gunnar Wagenknecht - Initial API and implementation
10   *     IBM Corporation - Initial API and implementation
11   **********************************************************************/
12  package org.eclipse.pde.build;
13  
14  import java.util.Map  ;
15  import java.util.Properties  ;
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IPath;
18  
19  /**
20   * Interface to be implemented by clients of the <code>org.eclipse.pde.build.fetchFactories</code> extension-point.
21   * <p>
22   * The factories are being used at various points in the execution of the PDE Build<code>eclipse.fetch</code> Ant task.
23   * Based on a map file entry, they are responsible for generating segments of an ant script whose execution will fetch 
24   * plug-ins, fragments, bundles and features or individual files contained in one of those elements.
25   * The format of a map file entry is:
26   * <code>
27   * &lt;elementType&gt;@&lt;elementName&gt; = &lt;repositoryTag&gt;, &lt;repositoryDetails&gt;
28   * </code>
29   * The format of <code>elementType</code> and <code>elementName</code> is fixed.
30   * The factories specify the value of <code>repositoryTag</code> and the format of the <code>repositoryDetails</code>.
31   * <code>repositoryTag</code> and <code>repositoryDetails</code> becomes defacto APIs. 
32   * </br>
33   * <code>repositoryTag</code> should match the factory id used when declaring the factory extension. For example, for the CVS the value is "CVS". 
34   * <code>repositoryDetails</code> should contains enough details to allow the factory to generate a fetch script retrieving the element.
35    * </p>
36   * <p>
37   * The fetch factories are being contributed through the <code>org.eclipse.pde.build.fetchFactories</code> 
38   * extension-points.
39   * </p>
40   * @since 3.2
41   */
42  public interface IFetchFactory {
43      /** Key used to store the value of the element name. */
44      public static final String   KEY_ELEMENT_NAME = "element"; //$NON-NLS-1$
45  
46      /** Key used to store the value of the element type */
47      public static final String   KEY_ELEMENT_TYPE = "type"; //$NON-NLS-1$
48  
49      /** Key used to store the value of the tag that will be used to fetch the element.
50       * <p>
51       *  The grammar of the expected value is limited to:
52       *  <pre>
53       *       value::= (alpha|digit|'_'|'-')+
54       *      digit ::= [0..9]
55       *      alpha ::= [a..zA..Z]
56       * </pre>
57       *  */
58      public static final String   KEY_ELEMENT_TAG = "tag"; //$NON-NLS-1$
59  
60      /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
61      public static final String   ELEMENT_TYPE_BUNDLE = "bundle"; //$NON-NLS-1$
62  
63      /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
64      public static final String   ELEMENT_TYPE_FEATURE = "feature"; //$NON-NLS-1$
65  
66      /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
67      public static final String   ELEMENT_TYPE_FRAGMENT = "fragment"; //$NON-NLS-1$
68  
69      /** One of the value for element type. See {@link #KEY_ELEMENT_TYPE}.*/
70      public static final String   ELEMENT_TYPE_PLUGIN = "plugin"; //$NON-NLS-1$
71  
72      /**
73       * This method should parse / validate a mapfile entry and derive a corresponding
74       * key / value pair structure containing the relevant information.
75       * <p>
76       * The arguments specified in the map file are provided. The map with entry
77       * infos should be filled with provider specific information that is
78       * required in later processing to sucessfully generate the fetch script.
79       * </p>
80       * 
81       * @param rawEntry the arguments as specified in the map file (may not be <code>null</code>).
82       * @param overrideTags a key / value containing all the override tags specified for all the repository (maybe <code>null</code> or empty). 
83       * The values of this map of this are read from the fetchTag property (see file scripts/templates/headless-build/build.properties). 
84       * @param entryInfos the map to store repository specific information derived from the rawEntry.This object is being passed as arguments to 
85       * 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 
86       * to fetch the element. This value is for example used to generate the "qualifier" value of a version number. 
87       * Note that {@link #KEY_ELEMENT_NAME} and {@link #KEY_ELEMENT_TYPE} are reserved entries whose values respectively 
88       * refer to the name of the element being fetched and its type.
89       * @throws CoreException if the rawEntry is incorrect.
90       */
91      public void parseMapFileEntry(String   rawEntry, Properties   overrideTags, Map   entryInfos) throws CoreException;
92      
93      /**
94       * Generates a segment of ant script whose execution will fetch the element (bundle, plug-in, fragment, feature) indicated in the entryInfos arguments.
95       * <p>
96       * @param entryInfos the map that has been built in the {@link #parseMapFileEntry(String, Properties, Map)} method.
97       * 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.
98       * @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
99       * to be in <code>destination/plugin.xml</code>. 
100      * @param script the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.  
101      */
102     public void generateRetrieveElementCall(Map   entryInfos, IPath destination, IAntScript script);
103     
104     /**
105      * Generates a segment of ant script whose execution will fetch the specified file from the given element.
106      * <p> 
107      * @param entryInfos the map that has been built in the {@link #parseMapFileEntry(String, Properties, Map)} method.
108      * 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.
109      * @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
110      * to be in <code>destination/plugin.xml</code>. 
111      * @param files the files to obtained for the specified element.
112      * @param script the script in which to generate the segments of ant script. It is not authorized to generate target declaration during this call.  
113      */
114     public void generateRetrieveFilesCall(Map   entryInfos, IPath destination, String  [] files, IAntScript script);
115 
116     /**
117      * This methods give opportunities to the factory to generate target declaration or other Ant top level constructs in the script.
118      * The generated elements can be invoked from the ant scripts segments created in {@link #generateRetrieveElementCall(Map, IPath, IAntScript)} 
119      * and {@link #generateRetrieveFilesCall(Map, IPath, String[], IAntScript)}.
120      */
121     public void addTargets(IAntScript script);
122 }
123
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags