General Information

Question (arch-what): What is this project good for?
Answer: Code Templates allow to paste various code snippets by using parametrized text. The parameters of the same name will share the same default value and if that value gets changed by user's typing the new value gets replicated into all the parameter's occurrences.
Code Templates replace the original abbreviations functionality.

Code template's example

for (Iterator ${iterator} = ${collection instanceof="java.util.Collection"}.iterator(); ${iterator}.hasNext();) {
    ${cursor}${iterator}.next();"
}

Each parameter can have additional hints of what values can be assigned to it. The hint has a form

${param hint=value}

or just

${param hint}

which translates to

${param hint="true"}

If necessary the value of the hint can be enclosed in quotes to allow to write whitespace or { or } into the value. The quote can be written by using \".

Reserved parameter names

${cursor} defines position where the caret will be located after the editing of the code template default values will finish.

Reserved hint names

${param editable=false} can be used to make the parameter to be skipped from user's editing. This may be useful e.g. with using java-specific type hint (described below).

Java:
${ind index} defines that the default value of the parameter should be an unused variable in the given context named i. If i is already used then j is attempted or then k etc. until z. Then i0, i1 etc. are attempted.
${param type="java.util.Collection"} defines java type that the parameter must be instance of. Besides class names there can be array e.g. String[] or generics java.util.List<String>
${param array} defines parameter of array type (including arrays of primitive data types).
${param type="java.util.Iterator"} defines that the parameter has the given java type. The template processing infrastructure will use short name Iterator and import java.util.Iterator.

Question (arch-overall): Describe the overall architecture.
Answer:

It is a module located under /cvs/editor/codetemplates directory.

It consists of
• API in org.netbeans.lib.editor.codetemplates.api
• SPI in org.netbeans.lib.editor.codetemplates.spi
• Implementation in org.netbeans.lib.editor.codetemplates

Code Templates define CodeTemplatesAPI.

Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module?
Answer:

Code Template Parameters

One of the main benefits of the code templates is their parametrization which allows to substitute the default values for the parameters before the final insertion and it also allows the user to modify these default values explicitly after the code template gets inserted into the document.
The parameters are marked in the code template's text by ${...}.
Parameters of the same name benefit from automatic replication. Once the template gets pasted into the document all the parameter's occurrences get replaced by parameter's default value.
The first parameter's occurrence gets selected.
The user can now replace the default value. If the user does so the new value gets replicated to all the other occurrences of this parameter automatically.

Mime-type specific operation

Each code template needs to find the default values for its parameters before it gets inserted into the text.
Sometimes it's enough to just specify the default value in the template's text but usually the default value gets determined from the context of insertion.
There is an intent to create a mime-type specific code template processor that would be registered per mime-type. There could be even more than one such processors processing the template in a specific order.

Parameter hints

Besides parameter's name the template processors may need additional hints of how to find a default value for the parameter.
For example java code template's parameter may be an index parameter which means that the infrastructure should fill in a fresh index variable e.g. i.
Or the parameter can only be of a certain java type such as in the case of iterating through a collection the type must be subtype of java.util.Collection.
These requirements could be specified as additional hints to the parameters e.g. ${i index} or ${c instanceof=java.util.Collection}.
The hints allow string literals to support arbitrary explicit default values specifications e.g. ${x default="Hello world"}.
The '{' and '}' have no special meaning inside the string literal.
The '"' char is allowed to be used by escaping ${x default="\"quoted string\""}.

Temporary Code Templates

The Code Completion functionality allows to build temporary Code Templates functionality if it could build a temporary template for completing of the method parameters. The parameters could be completed one by one by tabbing and the Code Templates framework would fill in proper default values just like it does for regular templates.

Insert Text Building and Updating

The parametrized text of the code template first gets parsed and the parameters get their default values which by default are the names of the parameters. The code template processor are then called to update this default value.
The new java infrastructure being developed would benefit from the possibility to obtain the full string containing the skeleton of the code template (without parameters) with the present default values. It can take that string and locally parse it to find out types of local variables used in the particular template and fill in dependent variable types.

Parameter Editability

Certain part of the code template may change text but it should not be edited by the user. For example when iterating over collection given as a parameter the collection may be generics-ed by additional type. The iterator's variable type then also needs to generics-ed with the same type.
The iterator's type parameter should not be editable because this operation may be done automatically by the java code template processor.
There should be a hint editable having true/false.
Question (arch-time): What are the time estimates of the work?
Answer: The work is expected to be finished into NetBeans 4.2.
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?
Answer: The unit tests are available in cvs/editor/codetemplates/test.
The following scenarios are tested:
• Correctness of the template parameters parsing.
• Correctness of the parameter's hints parsing.
Question (arch-where): Where one can find sources for your module?
Answer:

The sources for the module are in NetBeans CVS in editor/codetemplates directory.

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
Answer: EditorModuleAPI
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
Answer: No other projects.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?
Answer: All platforms.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
Answer: JDK1.4 and higher can be used.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough?
Answer: JRE is sufficient.

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
Answer: No additional files.
Question (deploy-nbm): Can you deploy an NBM via the Update Center?
Answer: Yes.
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere?
Answer: Anywhere.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
Answer: Yes, only the API and SPI are public. The implementation is not public.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one?
Answer:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.editor.codetemplates/1 > 1.2.31

Compatibility with environment

Question (compat-i18n): Is your module correctly internationalized?
Answer: Yes.
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow?
Answer: No implemented standards.
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version?
Answer: There will be default code templates provided by distribution and the user can create its own. They will be stored in xml files.

Access to resources

Question (resources-file): Does your module use java.io.File directly?
Answer: No.
Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components?
Answer: No.
Question (resources-read): Does your module read any resources from layers? For what purpose?
Answer: No.
Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers?
Answer: No.

Lookup of components

Question (lookup-lookup): Does your module use org.openide.util.Lookup or any similar technology to find any components to communicate with? Which ones?
Answer: Yes, it searches for Code Template Processors for particular mime-type by using org.netbeans.api.editor.mimelookup.MimeLookup -
Question (lookup-register): Do you register anything into lookup for other code to find?
Answer: No.
Question (lookup-remove): Do you remove entries of other modules from lookup?
Answer: No.

Execution Environment

Question (exec-property): Is execution of your code influenced by any environment or Java system (System.getProperty) property?
Answer: No.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
Answer: No.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use?
Answer: No.
Question (exec-classloader): Does your code create its own class loader(s)?
Answer: No.
Question (exec-reflection): Does your code use Java Reflection to execute other code?
Answer: No.
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection?
Answer: No.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code?
Answer: No.
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof, work with java.lang.Class, etc.)?
Answer: No.
Question (exec-threading): What threading models, if any, does your module adhere to?
Answer: No special threading models used.
Question (security-policy): Does your functionality require modifications to the standard policy file?
Answer: No.
Question (security-grant): Does your code grant additional rights to some other code?
Answer: No.

Format of files and protocols

Question (format-types): Which protocols and file formats (if any) does your module read or write on disk, or transmit or receive over the network? Do you generate an ant build script? Can it be edited and modified?
Answer: No files read or written to the disk.
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop?
Answer: No D&D.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods on java.awt.datatransfer.Transferable?
Answer: No clipboard support.

Performance and Scalability

Question (perf-startup): Does your module run any code on startup?
Answer: No.
Question (perf-exit): Does your module run any code on exit?
Answer: No.
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales?
Answer: Size and number of parameters of the code template.
Size of the editor's document slightly.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
Answer: No limits.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
Answer: Proportional to number of Code Templates which range from zero up to several tens for a typical mime-type.
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)?
Answer: No.
Question (perf-progress): Does your module execute any long-running tasks?
Answer: The code template processor may need to consult the context which can take considerable amount of time.
For example the java processor may need to consult MDR.
Still, once the user has requested pasting of the code template the the user will wait for the template to be pasted and will do no other typing.
Therefore there is no plan to reschedule the processor work into other threads than AWT.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas?
Answer: No.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?
Answer: No.
Question (perf-spi): How the performance of the plugged in code will be enforced?
Answer: The only plugged code should be code template processors that should just check the parameter's hints and possibly update the default value of the parameter.