001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.editor.settings;
043:
044: import java.util.ArrayList;
045: import java.util.Collections;
046: import java.util.List;
047:
048: /**
049: * The definition of a code template. A code template is basically a piece of
050: * code with an abbreviation associated to it. When a user types the abbreviation
051: * to the editor and presses the expansion key the code associated with the
052: * abbreviation gets expanded. The code can contain various parameters that the user
053: * can enter during the expansion.
054: *
055: * <p>The <code>CodeTemplateDescription</code>s can be obtained from
056: * <code>CodeTemplateSettings</code> class that can be loaded from <code>MimeLookup</code>
057: * for a particular mime type. See the example below.
058: *
059: * <pre>
060: * Lookup l = MimeLookup.getLookup(MimePath.parse(mimePath));
061: * CodeTemplateSettings cds = l.lookup(CodeTemplateSettings.class);
062: * List<CodeTemplateDescription> codeTemplates = cds.getCodeTemplateDescriptions();
063: * </pre>
064: *
065: * <p><b>IMPORTANT</b>: There is a much more powerful API for working with editor
066: * code templates in
067: * <a href="@org-netbeans-lib-editor-codetemplates@/overview-summary.html">Editor Code Templates</a>
068: * module. If you are retrieving this class from <code>MimeLookup</code> you should
069: * probably use the Editor Code Templates API instead.
070: *
071: * @see CodeTemplateSettings
072: * @author Miloslav Metelka
073: */
074: public final class CodeTemplateDescription {
075:
076: private final String abbreviation;
077: private final String description;
078: private final String parametrizedText;
079: private final List<String> contexts;
080: private final String uniqueId;
081: private final String mimePath;
082:
083: /**
084: * Creates a new code template description. It call the other constructor
085: * passing <code>null</code> for the <code>contexts</code> parameter.
086: *
087: * @param abbreviation The abbreviation text that expands this code template.
088: * @param description The code template's display text.
089: * @param parametrizedText The actual code template that will get expanded when
090: * a user writes the abbreviation in the editor.
091: */
092: public CodeTemplateDescription(String abbreviation,
093: String description, String parametrizedText) {
094: this (abbreviation, description, parametrizedText, null, null,
095: null);
096: }
097:
098: /**
099: * Creates a new code template description.
100: *
101: * <p>Usually clients do not need to create <code>CodeTemplateDescription</code>s
102: * by themselvs. Instead they use <code>MimeLookup</code> and <code>CodeTemplateSettings</code>
103: * to access code templates registered in the system.
104: *
105: * @param abbreviation The abbreviation text that expands this code template.
106: * @param description The code template's display text.
107: * Can be <code>null</code>
108: * @param parametrizedText The actual code template that will get expanded when
109: * a user writes the abbreviation in the editor.
110: * @param contexts The list of context ids that apply for this code template.
111: * Can be <code>null</code>
112: * @param uniqueId The id uniquely identifying this template. If you pass
113: * non-<code>null</code> value, please make sure that it is really a unique
114: * id for this template. Can be <code>null</code>.
115: */
116: public CodeTemplateDescription(String abbreviation,
117: String description, String parametrizedText,
118: List<String> contexts, String uniqueId) {
119: this (abbreviation, description, parametrizedText, contexts,
120: uniqueId, null);
121: }
122:
123: /**
124: * Creates a new code template description. The same as {@link #CodeTemplates(String, String, String, List<String>, String},
125: * but with additional <code>mimePath</code> parameter.
126: *
127: * @param abbreviation The abbreviation text that expands this code template.
128: * @param description The code template's display text.
129: * Can be <code>null</code>
130: * @param parametrizedText The actual code template that will get expanded when
131: * a user writes the abbreviation in the editor.
132: * @param contexts The list of context ids that apply for this code template.
133: * Can be <code>null</code>
134: * @param uniqueId The id uniquely identifying this template. If you pass
135: * non-<code>null</code> value, please make sure that it is really a unique
136: * id for this template. Can be <code>null</code>.
137: * @param mimePath The mime path where this code template description was registered for.
138: *
139: * @since 1.15
140: */
141: public CodeTemplateDescription(String abbreviation,
142: String description, String parametrizedText,
143: List<String> contexts, String uniqueId, String mimePath) {
144: assert abbreviation != null : "The abbreviation parameter can't be null"; //NOI18N
145: assert parametrizedText != null : "The parametrizedText parameter can't be null"; //NOI18N
146:
147: this .abbreviation = abbreviation;
148: this .description = description;
149: this .parametrizedText = parametrizedText;
150: this .contexts = contexts == null ? Collections
151: .<String> emptyList() : Collections
152: .unmodifiableList(new ArrayList<String>(contexts));
153: this .uniqueId = uniqueId;
154: this .mimePath = mimePath;
155: }
156:
157: /**
158: * Gets the abbreviation text that triggers expansion of this code template.
159: *
160: * <p>The abbreviation text should be unique among all code templates defined
161: * for a one mime type so that each code template can be expanded individually.
162: *
163: * @return The abbreviation text that expands this code template.
164: */
165: public String getAbbreviation() {
166: return abbreviation;
167: }
168:
169: /**
170: * Gets textual description of this code template. It's a display text
171: * that can be shown in UI such as the code completion window or Tools-Options
172: * dialog.
173: *
174: * @return The display text for this code template or <code>null</code> if this
175: * code template has no descriptions.
176: */
177: public String getDescription() {
178: return description;
179: }
180:
181: /**
182: * Gets the code text of this code template.
183: *
184: * This is the text that will be expanded when a user types the abbreviation
185: * in the editor and presses the expansion key. The text can contain parameters
186: * in the form of "${...}".
187: *
188: * @return The code text with parameters.
189: */
190: public String getParametrizedText() {
191: return parametrizedText;
192: }
193:
194: /**
195: * Gets the list of contexts that apply for this code template. The contexts
196: * are simply unique identifiers used by the infrastructure to filter out
197: * code templates that are not suitable for the editor context, where a user
198: * types.
199: *
200: * <p>The actual identifiers are defined by each particular language (mime type)
201: * and can be different for different languages. The language defines contexts
202: * for its constructs such as loops, methods, classes, if-else blocks, etc. and
203: * than tags each code template available for that language with a context,
204: * where it is meaningful to apply the template.
205: *
206: * @return The contexts for this code template.
207: */
208: public List<String> getContexts() {
209: return contexts;
210: }
211:
212: /**
213: * Gets an id that can be used for identifying this template. A code template
214: * does not generally have to have a unique id, but if it has one it is
215: * guaranteed to uniquely identify the template.
216: *
217: * <p class="nonnormative">Unique ids can be useful for tools importing and
218: * exporting code templates from other applications such as TextMate, etc.
219: *
220: * @return The unique id or <code>null</code>.
221: * @since 1.11
222: */
223: public String getUniqueId() {
224: return uniqueId;
225: }
226:
227: /**
228: * Gets the mime path where this code template was registered.
229: *
230: * @return The mime path string or <code>null</code> if the registration mime
231: * path is unknown.
232: * @since 1.15
233: */
234: public String getMimePath() {
235: return mimePath;
236: }
237:
238: public @Override
239: String toString() {
240: return "abbrev='" + getAbbreviation() + "', parametrizedText='"
241: + getParametrizedText() + "'"; // NOI18N
242: }
243:
244: /**
245: * Checks whether this code template is equal with a code template passed in
246: * as the <code>obj</code> parameter. By definition two code templates are
247: * equal if all their fields are equal - ie. all abbreviation, description,
248: * parametrizedText, contexts, uniqueId and mimePath fields are equal.
249: *
250: * @param obj The code template to compare with.
251: *
252: * @return <code>true</code> if and only if this code template is equal to
253: * the <code>obj</code> code template.
254: */
255: public @Override
256: boolean equals(Object obj) {
257: if (obj == null) {
258: return false;
259: }
260: if (getClass() != obj.getClass()) {
261: return false;
262: }
263: final CodeTemplateDescription other = (CodeTemplateDescription) obj;
264: if ((this .abbreviation == null && other.abbreviation != null)
265: || (this .abbreviation != null && other.abbreviation == null)
266: || (this .abbreviation != null && !this .abbreviation
267: .equals(other.abbreviation))) {
268: return false;
269: }
270: if ((this .description == null && other.description != null)
271: || (this .description != null && other.description == null)
272: || (this .description != null && !this .description
273: .equals(other.description))) {
274: return false;
275: }
276: if ((this .parametrizedText == null && other.parametrizedText != null)
277: || (this .parametrizedText != null && other.parametrizedText == null)
278: || (this .parametrizedText != null && !this .parametrizedText
279: .equals(other.parametrizedText))) {
280: return false;
281: }
282: if (this .contexts != other.contexts
283: && (this .contexts == null || !this .contexts
284: .equals(other.contexts))) {
285: return false;
286: }
287: if ((this .uniqueId == null && other.uniqueId != null)
288: || (this .uniqueId != null && other.uniqueId == null)
289: || (this .uniqueId != null && !this .uniqueId
290: .equals(other.uniqueId))) {
291: return false;
292: }
293: if ((this .mimePath == null && other.mimePath != null)
294: || (this .mimePath != null && other.mimePath == null)
295: || (this .mimePath != null && !this .mimePath
296: .equals(other.mimePath))) {
297: return false;
298: }
299: return true;
300: }
301:
302: public @Override
303: int hashCode() {
304: int hash = 3;
305: hash = 59
306: * hash
307: + (this .abbreviation != null ? this .abbreviation
308: .hashCode() : 0);
309: hash = 59
310: * hash
311: + (this .description != null ? this .description
312: .hashCode() : 0);
313: hash = 59
314: * hash
315: + (this .parametrizedText != null ? this .parametrizedText
316: .hashCode()
317: : 0);
318: hash = 59
319: * hash
320: + (this .contexts != null ? this .contexts.hashCode() : 0);
321: hash = 59
322: * hash
323: + (this .uniqueId != null ? this .uniqueId.hashCode() : 0);
324: hash = 59
325: * hash
326: + (this .mimePath != null ? this .mimePath.hashCode() : 0);
327: return hash;
328: }
329:
330: }
|