001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation 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: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.pde.ui.templates;
011:
012: import java.net.URL;
013:
014: import org.eclipse.core.resources.IProject;
015: import org.eclipse.core.runtime.CoreException;
016: import org.eclipse.core.runtime.IProgressMonitor;
017: import org.eclipse.jface.wizard.Wizard;
018: import org.eclipse.jface.wizard.WizardPage;
019: import org.eclipse.pde.core.plugin.IPluginModelBase;
020: import org.eclipse.pde.core.plugin.IPluginReference;
021:
022: /**
023: * This interface represents a section of the template wizard that generates a
024: * new extension or plug-in. Typically, it maps to one wizard page, but more
025: * complex sections may span several pages. Also note that in the very simple
026: * cases it may not contribute any wizard pages.
027: * <p>
028: * If a section generates extensions, it should be written in such a way to be
029: * used both in the 'New Extension' wizard and as a part of a new plug-in
030: * project wizard. When used as part of the new plug-in project wizard, it may
031: * appear alongside other templates and therefore should not do anything that
032: * prevents it.
033: *
034: * @since 2.0
035: */
036:
037: public interface ITemplateSection {
038: /**
039: * Returns the URL of the zip file containing template files and directories
040: * that will be created in the plug-in project. If URL protocol is 'file',
041: * and the URL ends with a trailing file separator, an attempt will be made
042: * to treat the URL as a root directory and iterate using standard Java I/O
043: * classes. If template files are stored in a ZIP or JAR archive, the name
044: * of the archive must be part of the URL.
045: *
046: * @return a template location URL
047: */
048: public URL getTemplateLocation();
049:
050: /**
051: * Returns a presentable label the section.
052: *
053: * @return a template label
054: */
055: public String getLabel();
056:
057: /**
058: * Returns a description of the section. The description should explain what
059: * extension will be used, what classes will be generated and how to test
060: * that the generated code works properly.
061: *
062: * @return a template description
063: */
064: public String getDescription();
065:
066: /**
067: * Returns a replacement string for the provided key. When a token is found
068: * in the template file with a form '$key$', the actual key is passed to
069: * this method to obtain the replacement. If replacement is provided, it is
070: * substituted for the token (including the '$' characters). Otherwise, it
071: * is transfered as-is.
072: *
073: * @param fileName
074: * the name of the file in which the key was found. You can use
075: * it to return different values for different files.
076: * @param key
077: * the replacement key found in the template file
078: * @return replacement string for the provided key, or the key itself if not
079: * found.
080: */
081: public String getReplacementString(String fileName, String key);
082:
083: /**
084: * Adds template-related pages to the wizard. A typical section
085: * implementation contributes one page, but complex sections may span
086: * several pages.
087: *
088: * @param wizard
089: * the host wizard to add pages into
090: */
091: public void addPages(Wizard wizard);
092:
093: /**
094: * Returns a wizard page at the provided index.
095: *
096: * @return wizard page index.
097: */
098: public WizardPage getPage(int pageIndex);
099:
100: /**
101: * Returns number of pages that are contributed by this template.
102: */
103: public int getPageCount();
104:
105: /**
106: * Tests whether this template have had a chance to create its pages. This
107: * method returns true after 'addPages' has been called.
108: *
109: * @return <samp>true </samp> if wizard pages have been created by this
110: * template.
111: */
112:
113: public boolean getPagesAdded();
114:
115: /**
116: * Returns the number of work units that this template will consume during
117: * the execution. This number is used to calculate the total number of work
118: * units when initializing the progress indicator.
119: *
120: * @return the number of work units
121: */
122: public int getNumberOfWorkUnits();
123:
124: /**
125: * Provides the list of template dependencies. A template may generate a
126: * number of Java classes that reference classes and interfaces from other
127: * plug-ins. By providing this list, a template enables the template wizard
128: * to create the correct Java build path so that these classes and
129: * interfaces are correctly resolved.
130: *
131: * @param schemaVersion
132: * version of the target manifest, or <samp>null </samp> if older
133: * manifest (prior to 3.0) will be created. Depending on the
134: * manifest version, the list of dependencies may vary.
135: *
136: * @return an array of template dependencies
137: */
138: public IPluginReference[] getDependencies(String schemaVersion);
139:
140: /**
141: * Returns identifier of the extension point used in this section.
142: *
143: * @return extension point id if this section contributes into an extension
144: * point or <samp>null </samp> if not applicable.
145: */
146: public String getUsedExtensionPoint();
147:
148: /**
149: * Executes the template. As part of the execution, template may generate
150: * resources under the provided project, and/or modify the plug-in model.
151: *
152: * @param project
153: * the workspace project that contains the plug-in
154: * @param model
155: * structured representation of the plug-in manifest
156: * @param monitor
157: * progress monitor to indicate execution progress
158: */
159: public void execute(IProject project, IPluginModelBase model,
160: IProgressMonitor monitor) throws CoreException;
161:
162: /**
163: * Returns an array of tokens representing new files and folders created by
164: * this template section. The information is collected for the benefit of
165: * <code>build.properties</code> file so that the generated files and
166: * folders are included in the binary build. The tokens will be added as-is
167: * to the variable <code>bin.includes</code>. For this reason, wild cards
168: * and other syntax rules applicable to this variable can be used in this
169: * method. For example:
170: * <p>
171: *
172: * <pre>
173: * return new String[]{"/icons/*.gif"};
174: * </pre>
175: *
176: * </p>
177: *
178: * @return an array of strings that fully describe the files and folders
179: * created by this template section as required by <code>
180: * bin.includes</code> variable in <code>build.properties</code>
181: * file.
182: */
183: public String[] getNewFiles();
184: }
|