ITemplateSection


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation 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    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.pde.ui.templates;
12  import java.net.URL  ;
13  
14  import org.eclipse.core.resources.IProject;
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.core.runtime.IProgressMonitor;
17  import org.eclipse.jface.wizard.Wizard;
18  import org.eclipse.jface.wizard.WizardPage;
19  import org.eclipse.pde.core.plugin.IPluginModelBase;
20  import org.eclipse.pde.core.plugin.IPluginReference;
21  
22  /**
23   * This interface represents a section of the template wizard that generates a
24   * new extension or plug-in. Typically, it maps to one wizard page, but more
25   * complex sections may span several pages. Also note that in the very simple
26   * cases it may not contribute any wizard pages.
27   * <p>
28   * If a section generates extensions, it should be written in such a way to be
29   * used both in the 'New Extension' wizard and as a part of a new plug-in
30   * project wizard. When used as part of the new plug-in project wizard, it may
31   * appear alongside other templates and therefore should not do anything that
32   * prevents it.
33   * 
34   * @since 2.0
35   */
36  
37  public interface ITemplateSection {
38      /**
39       * Returns the URL of the zip file containing template files and directories
40       * that will be created in the plug-in project. If URL protocol is 'file',
41       * and the URL ends with a trailing file separator, an attempt will be made
42       * to treat the URL as a root directory and iterate using standard Java I/O
43       * classes. If template files are stored in a ZIP or JAR archive, the name
44       * of the archive must be part of the URL.
45       * 
46       * @return a template location URL
47       */
48      public URL   getTemplateLocation();
49      /**
50       * Returns a presentable label the section.
51       * 
52       * @return a template label
53       */
54      public String   getLabel();
55  
56      /**
57       * Returns a description of the section. The description should explain what
58       * extension will be used, what classes will be generated and how to test
59       * that the generated code works properly.
60       * 
61       * @return a template description
62       */
63      public String   getDescription();
64  
65      /**
66       * Returns a replacement string for the provided key. When a token is found
67       * in the template file with a form '$key$', the actual key is passed to
68       * this method to obtain the replacement. If replacement is provided, it is
69       * substituted for the token (including the '$' characters). Otherwise, it
70       * is transfered as-is.
71       * 
72       * @param fileName
73       *            the name of the file in which the key was found. You can use
74       *            it to return different values for different files.
75       * @param key
76       *            the replacement key found in the template file
77       * @return replacement string for the provided key, or the key itself if not
78       *         found.
79       */
80      public String   getReplacementString(String   fileName, String   key);
81      /**
82       * Adds template-related pages to the wizard. A typical section
83       * implementation contributes one page, but complex sections may span
84       * several pages.
85       * 
86       * @param wizard
87       *            the host wizard to add pages into
88       */
89      public void addPages(Wizard wizard);
90  
91      /**
92       * Returns a wizard page at the provided index.
93       * 
94       * @return wizard page index.
95       */
96      public WizardPage getPage(int pageIndex);
97  
98      /**
99       * Returns number of pages that are contributed by this template.
100      */
101     public int getPageCount();
102 
103     /**
104      * Tests whether this template have had a chance to create its pages. This
105      * method returns true after 'addPages' has been called.
106      * 
107      * @return <samp>true </samp> if wizard pages have been created by this
108      *         template.
109      */
110 
111     public boolean getPagesAdded();
112 
113     /**
114      * Returns the number of work units that this template will consume during
115      * the execution. This number is used to calculate the total number of work
116      * units when initializing the progress indicator.
117      * 
118      * @return the number of work units
119      */
120     public int getNumberOfWorkUnits();
121 
122     /**
123      * Provides the list of template dependencies. A template may generate a
124      * number of Java classes that reference classes and interfaces from other
125      * plug-ins. By providing this list, a template enables the template wizard
126      * to create the correct Java build path so that these classes and
127      * interfaces are correctly resolved.
128      * 
129      * @param schemaVersion
130      *            version of the target manifest, or <samp>null </samp> if older
131      *            manifest (prior to 3.0) will be created. Depending on the
132      *            manifest version, the list of dependencies may vary.
133      *            
134      * @return an array of template dependencies
135      */
136     public IPluginReference[] getDependencies(String   schemaVersion);
137 
138     /**
139      * Returns identifier of the extension point used in this section.
140      * 
141      * @return extension point id if this section contributes into an extension
142      *         point or <samp>null </samp> if not applicable.
143      */
144     public String   getUsedExtensionPoint();
145 
146     /**
147      * Executes the template. As part of the execution, template may generate
148      * resources under the provided project, and/or modify the plug-in model.
149      * 
150      * @param project
151      *            the workspace project that contains the plug-in
152      * @param model
153      *            structured representation of the plug-in manifest
154      * @param monitor
155      *            progress monitor to indicate execution progress
156      */
157     public void execute(IProject project, IPluginModelBase model,
158             IProgressMonitor monitor) throws CoreException;
159 
160     /**
161      * Returns an array of tokens representing new files and folders created by
162      * this template section. The information is collected for the benefit of
163      * <code>build.properties</code> file so that the generated files and
164      * folders are included in the binary build. The tokens will be added as-is
165      * to the variable <code>bin.includes</code>. For this reason, wild cards
166      * and other syntax rules applicable to this variable can be used in this
167      * method. For example:
168      * <p>
169      * 
170      * <pre>
171      * return new String[]{&quot;/icons/*.gif&quot;};
172      * </pre>
173      * 
174      * </p>
175      * 
176      * @return an array of strings that fully describe the files and folders
177      *         created by this template section as required by <code>
178      *         bin.includes</code> variable in <code>build.properties</code>
179      *         file.
180      */
181     public String  [] getNewFiles();
182 }
183
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags