General Information
Question (arch-what):
What is this project good for?
Answer:
org.netbeans.api.jackpot
This project adds reengineering capabilities to NetBeans, similar to
refactoring but generally larger in scope.
Question (arch-overall):
Describe the overall architecture.
Answer:
The Jackpot API provides programmatic access to the Jackpot query and transformation module.
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:
Jackpot Commands
Developers creating new Jackpot query and transformer commands
which cannot be implemented using the Jackpot rules language. The
rules language can be used to match and transform most Java
language statements and expressions. Developers who need complete
access to Jackpot's model of the Java source can do
so via its API instead.
Modules
New queries and transformers are deployed by independent developers
using NetBeans modules.
Question (arch-time):
What are the time estimates of the work?
Answer:
This API is currently planned for the NetBeans 6.0 release timeframe.
Question (arch-quality):
How will the quality
of your code be tested and
how are future regressions going to be prevented?
Answer:
Currently no testing infrastructure exists, other than its use by the
module's built-in queries and transformers.
Question (arch-where):
Where one can find sources for your module?
Answer:
The sources for the module are in NetBeans
CVS in
jackpot
directory.
Project and platform dependencies
Question (dep-nb):
What other NetBeans projects and modules does this one depend on?
Answer:
These modules are required in project.xml:
-
org.jdesktop.layout
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.1.1
is required.
-
org.netbeans.api.java
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.8
is required.
-
org.netbeans.api.progress
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.0
is required.
-
org.netbeans.libs.javacapi
-
The module is needed for compilation.
The module is used during runtime.
-
org.netbeans.modules.classfile
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.19
is required.
-
org.netbeans.modules.diff
-
The module is needed for compilation.
The module is used during runtime.
-
org.netbeans.modules.java.platform
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.9
is required.
-
org.netbeans.modules.java.project
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.5
is required.
-
org.netbeans.modules.java.source
-
The module is needed for compilation.
The module is used during runtime.
Specification version
0.4
is required.
-
org.netbeans.modules.options.api
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.5
is required.
-
org.netbeans.modules.projectapi
-
The module is needed for compilation.
The module is used during runtime.
Specification version
1.5
is required.
-
org.netbeans.modules.projectuiapi
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.actions
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
org.openide.awt
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.dialogs
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
org.openide.filesystems
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.io
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.loaders
-
The module is needed for compilation.
The module is used during runtime.
Specification version
5.4
is required.
-
org.openide.modules
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.nodes
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
org.openide.text
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
org.openide.util
-
The module is needed for compilation.
The module is used during runtime.
-
org.openide.windows
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
Question (dep-non-nb):
What other projects outside NetBeans does this one depend on?
Answer:
None.
Question (dep-platform):
On which platforms does your module run? Does it run in the same
way on each?
Answer:
The Jackpot module is platform-independent.
Question (dep-jre):
Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
Answer:
The Jackpot module requires JRE 1.5.
Question (dep-jrejdk):
Do you require the JDK or is the JRE enough?
Answer:
The JRE is sufficient.
Deployment
Question (deploy-jar):
Do you deploy just module JAR file(s) or other files as well?
Answer:
The Jackpot module is defined by a normal module JAR.
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:
This module can be deployed anywhere.
Question (deploy-packages):
Are packages of your module made inaccessible by not declaring them
public?
Answer:
Yes, only the public API packages are made 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
Access to resources
Question (resources-file):
Does your module use java.io.File directly?
Answer:
Yes, for its class loading and when generating class files from scripts.
FileObjects are used whenever possible, however.
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:
Yes. The Jackpot module defines a service directory where queries are
declared, and a second directory for query lists (groups) are declared.
This layer can be modified by the user using the Refactoring Manager
dialog to add, delete and modify the available queries used by the
Query and Refactor dialog. Independent modules add their queries and
query lists using these layers.
Question (resources-read):
Does your module read any resources from layers? For what purpose?
Answer:
Yes, the official layers used for declaring actions, menu entries, JavaHelp,
editor annotation type, window modes and components.
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 ?
Answer:
The Jackpot module uses the Preferences API so that transformer preferences can be
referenced by future command-line tools. Currently only unit tests are run outside of
the IDE, but a command-line version of Jackpot is planned.
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. The Jackpot module uses Lookup to find Query
classes defined in other modules. This lookup is done during execution of a query defined by that
module, so only a single specified class is searched for. Order therefore doesn't matter.
Question (lookup-register):
Do you register anything into lookup for other code to find?
Answer:
Just normal NetBeans UI services including actions, menu entries, JavaHelp,
editor annotation type, window mode and window component.
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?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger? Or do you observe
what others log?
Answer:
Nothing public. Log levels can be set to get diagnostic information, but
that would normally only be interesting to the engineers supporting the
module, not its users.
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:
Yes. A classloader is used to dynamically create and load a query during its
execution. This allows other modules to be independently updated without
restarting, and ensures that all javac references are released after each
execution.
Question (exec-reflection):
Does your code use Java Reflection to execute other code?
Answer:
No. Reflection is only used within the Jackpot module to look for JavaBean
properties on queries.
Question (exec-privateaccess):
Are you aware of any other parts of the system calling some of
your methods by reflection?
Answer:
No use of reflection is supported.
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:
While the module uses instanceof internally, its API does not have any
restrictions which require documentation.
Question (exec-threading):
What threading models, if any, does your module adhere to? How the
project behaves with respect to threading?
Answer:
No threading model should be referenced by clients of the Jackpot API. Queries
and transformer classes written using it are executed in a single thread by a
container-like runtime provided by the Jackpot module.
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:
Java source files are read and written.
Question (format-dnd):
Which protocols (if any) does your code understand during Drag & Drop?
Answer:
No drag-and-drop protocols are defined or referenced.
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 data flavors are defined or referenced.
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:
The number of source files in a project.
Question (perf-limit):
Are there any hard-coded or practical limits in the number or size of
elements your code can handle?
Answer:
Not itself, but it depends upon the limits of the Java Source module.
Question (perf-mem):
How much memory does your component consume? Estimate
with a relation to the number of windows, etc.
Answer:
Unknown. There is a dialog initiating the query, and a results window that
lists matches and modifications (similar to the Refactoring window). Memory
consumed during execution of a query is determined by the Java Source module.
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:
Yes, potentially. Although most visiter classes execute quickly, it is
possible to write ones that do not (especially when doing call-graph
analysis). These run as cancellable tasks.
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:
Yes, the Refactoring Manager dialog.
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:
There is no enforcement, as this module relies upon the Java Source module
to execute queries and transformations. That module needs to provide any
necessary memory enforcement.
