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
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.
JTextComponent pane = ...
String tempCodeTemplateText = ...
CodeTemplate ct = CodeTemplateManager.get(pane.getDocument()).createTemporary(tempCodeTemplateText);
ct.insert(pane);
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 the
NetBeans Mercurial repositories.
Project and platform dependencies
Question (dep-nb):
What other NetBeans projects and modules does this one depend on?
Answer:
-
EditorModuleAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.24
is required.
-
CodeCompletionAPI
-
The module is needed for compilation.
The module is used during runtime.
-
EditorHyperlinkSPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.3
is required.
-
MimeLookupAPI
-
The module is needed for compilation.
The module is used during runtime.
-
EditorSettingsAPI
-
The module is needed for compilation.
The module is used during runtime.
-
EditorUtilitiesAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.5
is required.
-
org.netbeans.spi.editor.hints
-
The module is needed for compilation.
The module is used during runtime.
-
FilesystemsAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
7.0
is required.
-
ModulesAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
org.openide.options
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
EditorAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.16
is required.
-
UtilitiesAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
WindowSystemAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.7
is required.
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,
in addition to or instead of the normal module dependency declaration
(e.g. tokens to require)?
Answer:
Nothing.
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.
Question (compat-deprecation):
How the introduction of your project influences functionality
provided by previous version of the product?
WARNING: Question with id="compat-deprecation" has not been answered!
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.
Question (resources-preferences):
Does your module uses preferences via Preferences API? Does your module use NbPreferences or
or regular JDK Preferences ? Does it read, write or both ?
Does it share preferences with other modules ? If so, then why ?
WARNING: Question with id="resources-preferences" has not been answered!
Lookup of components
Execution Environment
Question (exec-property):
Is execution of your code influenced by any environment or
Java system (System.getProperty) property?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger? Or do you observe
what others log?
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? How the
project behaves with respect to threading?
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.