KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > lib > editor > codetemplates > spi > CodeTemplateInsertRequest


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.lib.editor.codetemplates.spi;
21 import java.util.Iterator JavaDoc;
22 import java.util.List JavaDoc;
23 import javax.swing.text.JTextComponent JavaDoc;
24 import org.netbeans.lib.editor.codetemplates.CodeTemplateInsertHandler;
25 import org.netbeans.lib.editor.codetemplates.CodeTemplateParameterImpl;
26 import org.netbeans.lib.editor.codetemplates.CodeTemplateSpiPackageAccessor;
27 import org.netbeans.lib.editor.codetemplates.api.CodeTemplate;
28
29 /**
30  * Code template insert request parses the code template's text
31  * to gather the data necessary to insert
32  * the particular code template into the document (such as the template's parameters).
33  *
34  * <h3>State</h3>
35  * The insert request can be in three states:
36  * <ul>
37  * <li>It is not inserted into the document yet.
38  * Both {@link #isInserted()} and {@link #isReleased()}
39  * return false. Registered {@link CodeTemplateProcessor}s
40  * will be asked to fill in the default values into the parameters.
41  * <li>It is inserted and the user modifies the parameters' values in the document.
42  * {@link #isInserted()} returns true and {@link #isReleased()} returns false.
43  * <li>It is released. {@link #isReleased()} returns true. There is no more
44  * work to do. Code templates processor(s) servicing the request will be released.
45  * </ul>
46  *
47  * <h3>Parameters</h3>
48  * The code template's text is first parsed to find the parameters.
49  * Each first occurrence of a parameter with particular name define
50  * a master parameter. All the other occurrences of a parameter with the same name
51  * define slave parameters (of the previously defined master).
52  *
53  * @see CodeTemplateParameter
54  *
55  *
56  * @author Miloslav Metelka
57  */
58 public final class CodeTemplateInsertRequest {
59     
60     static {
61         CodeTemplateSpiPackageAccessor.register(new SpiAccessor());
62     }
63     
64     private final CodeTemplateInsertHandler handler;
65     
66     CodeTemplateInsertRequest(CodeTemplateInsertHandler handler) {
67         this.handler = handler;
68     }
69
70     /**
71      * Get code template associated with this insert request.
72      */
73     public CodeTemplate getCodeTemplate() {
74         return handler.getCodeTemplate();
75     }
76
77     /**
78      * Get the text component into which the template should be inserted
79      * at the current caret position.
80      */
81     public JTextComponent JavaDoc getComponent() {
82         return handler.getComponent();
83     }
84     
85     /**
86      * Get list of master parameters in the order they are located
87      * in the code template text.
88      * <br>
89      * The master parameters can be explored by the code template processor
90      * and their default values can be changed as necessary.
91      *
92      * @return non-null unmodifiable list of master parameters.
93      */
94     public List JavaDoc/*<CodeTemplateParameter>*/ getMasterParameters() {
95         return handler.getMasterParameters();
96     }
97     
98     /**
99      * Get master parameter with the given name.
100      *
101      * @param name non-null name of the master parameter to be searched.
102      * @return master parameter with the given name or null if no such
103      * parameter exists.
104      */
105     public CodeTemplateParameter getMasterParameter(String JavaDoc name) {
106         for (Iterator JavaDoc it = getMasterParameters().iterator(); it.hasNext();) {
107             CodeTemplateParameter master = (CodeTemplateParameter)it.next();
108             if (name.equals(master.getName())) {
109                 return master;
110             }
111         }
112         return null;
113     }
114
115     /**
116      * Get all the parameters (masters and slaves)
117      * present in the code template text in the order as they occur
118      * in the parametrized text.
119      *
120      * @return non-null unmodifiable list of all parameters.
121      * @see #getMasterParameters()
122      */
123     public List JavaDoc/*<CodeTemplateParameter>*/ getAllParameters() {
124         return handler.getAllParameters();
125     }
126     
127     /**
128      * Check whether the code template that this request
129      * represents was already inserted into the document.
130      *
131      * @return true if the code template was already inserted into the document
132      * and the inserted default values are being modified by the user
133      * which can result into
134      * {@link CodeTemplateProcessor#parameterValueChanged(CodeTemplateParameter, boolean)}.
135      * <p/>
136      * Returns false if the code template was not yet inserted into the document
137      * i.e. the {@link CodeTemplateProcessor#updateDefaultValues()}
138      * is currently being called on the registered processors.
139      * @see #isReleased()
140      */
141     public boolean isInserted() {
142         return handler.isInserted();
143     }
144     
145     /**
146      * Check whether this request is already released which means
147      * that the code template was inserted and values of all the parameters
148      * were modified by the user so there is no more work to be done.
149      *
150      * @return whether this request is already released or not.
151      * If the request was not yet released then {@link #isInserted()}
152      * gives additional info whether request is inserted into the document or not.
153      * @see #isInserted()
154      */
155     public boolean isReleased() {
156         return handler.isReleased();
157     }
158     
159     /**
160      * Get the present parametrized text handled by this request.
161      * <br/>
162      * By default the code template's parametrized text obtained
163      * by {@link CodeTemplate#getParametrizedText()} is used.
164      * <br/>
165      * The parametrized text can be modified by {@link #setParametrizedText(String)}.
166      */
167     public String JavaDoc getParametrizedText() {
168         return handler.getParametrizedText();
169     }
170     
171     /**
172      * Set the parametrized text to a new value.
173      * <br/>
174      * This may be necessary if some parameters are just artificial
175      * and should be expanded by a particular code template processor
176      * before the regular processing.
177      * <br/>
178      * Once this method is called the new parametrized text will be parsed
179      * and a fresh new list of parameters will be created.
180      *
181      * @param parametrizedText new parametrized text to be used.
182      */
183     public void setParametrizedText(String JavaDoc parametrizedText) {
184         handler.setParametrizedText(parametrizedText);
185     }
186
187     /**
188      * Get the text where all the parameters are replaced
189      * by their present values.
190      * <br/>
191      * This is the text to be physically inserted into the document
192      * once the template processors possibly update the parameter's values.
193      * <br/>
194      * After the text gets physically inserted into the document this method
195      * continues to return the "living" text of the document with the inserted template.
196      */
197     public String JavaDoc getInsertText() {
198         return handler.getInsertText();
199     }
200
201     /**
202      * Return offset of the inserted template in the document's text.
203      * <br/>
204      * The offset is physically represented as a swing position
205      * so it will reflect possible subsequent document mutations.
206      * <br/>
207      * Before the template gets inserted into the document this method
208      * returns zero.
209      */
210     public int getInsertTextOffset() {
211         return handler.getInsertOffset();
212     }
213
214     private static final class SpiAccessor extends CodeTemplateSpiPackageAccessor {
215         
216         public CodeTemplateInsertRequest createInsertRequest(CodeTemplateInsertHandler handler) {
217             return new CodeTemplateInsertRequest(handler);
218         }
219
220         public CodeTemplateParameter createParameter(CodeTemplateParameterImpl impl) {
221             return new CodeTemplateParameter(impl);
222         }
223         
224         public CodeTemplateParameterImpl getImpl(CodeTemplateParameter parameter) {
225             return parameter.getImpl();
226         }
227
228     }
229
230 }
231
Popular Tags