1 <?xml version="1.0" encoding="UTF-8"?>
3 The contents of this file are subject to the terms of the Common Development
4 and Distribution License (the License). You may not use this file except in
5 compliance with the License.
7 You can obtain a copy of the License at http://www.netbeans.org/cddl.html
8 or http://www.netbeans.org/cddl.txt.
10 When distributing Covered Code, include this CDDL Header Notice in each file
11 and include the License file at http://www.netbeans.org/cddl.txt.
12 If applicable, add the following below the CDDL Header, with the fields
13 enclosed by brackets [] replaced by your own identifying information:
14 "Portions Copyrighted [year] [name of copyright owner]"
16 The Original Software is NetBeans. The Initial Developer of the Original
17 Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
18 Microsystems, Inc. All Rights Reserved.
20 <!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
21 <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
25 question-version="1.29"
26 author="yourname@netbeans.org"
33 <question id="arch-overall" when="init">
34 Describe the overall architecture.
37 <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi">
38 clients and what support API</a>?
39 What parts will be pluggable?
40 How will plug-ins be registered? Please use <code><api type="export"/></code>
41 to describe your general APIs and specify their
42 <a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">
43 stability categories</a>.
44 If possible please provide simple diagrams.
48 <answer id="arch-overall">
50 Lookup and the Springframework's injection mechanism seem to be quite
51 similar. This module is here to create a bridge between these two.
58 <question id="arch-quality" when="init">
59 How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html">quality</a>
60 of your code be tested and
61 how are future regressions going to be prevented?
63 What kind of testing do
64 you want to use? How much functionality, in which areas,
65 should be covered by the tests? How you find out that your
66 project was successful?
70 <answer id="arch-quality">
78 <answer id="arch-time">
80 Initial version ready in 2008, more enhance features per request and contribution.
87 <question id="arch-usecases" when="init">
89 Content of this answer will be displayed as part of page at
90 http://www.netbeans.org/download/dev/javadoc/usecases.html
91 You can use tags <usecase name="name> regular html description </usecase>
92 and if you want to use an URL you can prefix if with @TOP@ to begin
93 at the root of your javadoc
96 Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase">
97 use cases</a> of the new API. Who will use it under
98 what circumstances? What kind of code would typically need to be written
102 <answer id="arch-usecases">
104 XXX no answer for arch-usecases
111 <question id="arch-what" when="init">
112 What is this project good for?
114 Please provide here a few lines describing the project,
115 what problem it should solve, provide links to documentation,
120 <answer id="arch-what">
122 <api name="org.netbeans.api.spring" category="official" group="java" type="export"
123 url="@TOP@/org/netbeans/api/spring/package-summary.html"
125 API for bridging Springframework injection mechanism and Lookup
133 <question id="arch-where" when="impl">
134 Where one can find sources for your module?
136 Please provide link to the Hg web client at
137 http://hg.netbeans.org/
138 or just use tag defaultanswer generate='here'
142 <answer id="arch-where">
143 <defaultanswer generate='here' />
149 <question id="compat-deprecation" when="init">
150 How the introduction of your project influences functionality
151 provided by previous version of the product?
153 If you are planning to deprecate/remove/change any existing APIs,
154 list them here accompanied with the reason explaining why you
159 <answer id="compat-deprecation">
161 XXX no answer for compat-deprecation
168 <question id="compat-i18n" when="impl">
169 Is your module correctly internationalized?
171 Correct internationalization means that it obeys instructions
172 at <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/i18n-branding.html">
173 NetBeans I18N pages</a>.
177 <answer id="compat-i18n">
179 XXX no answer for compat-i18n
186 <question id="compat-standards" when="init">
187 Does the module implement or define any standards? Is the
188 implementation exact or does it deviate somehow?
191 <answer id="compat-standards">
193 XXX no answer for compat-standards
200 <question id="compat-version" when="impl">
201 Can your module coexist with earlier and future
202 versions of itself? Can you correctly read all old settings? Will future
203 versions be able to read your current settings? Can you read
204 or politely ignore settings stored by a future version?
207 Very helpful for reading settings is to store version number
208 there, so future versions can decide whether how to read/convert
209 the settings and older versions can ignore the new ones.
213 <answer id="compat-version">
215 XXX no answer for compat-version
222 <question id="dep-jre" when="final">
223 Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
225 It is expected that if your module runs on 1.x that it will run
226 on 1.x+1 if no, state that please. Also describe here cases where
227 you run different code on different versions of JRE and why.
231 <answer id="dep-jre">
233 XXX no answer for dep-jre
240 <question id="dep-jrejdk" when="final">
241 Do you require the JDK or is the JRE enough?
244 <answer id="dep-jrejdk">
246 XXX no answer for dep-jrejdk
253 <question id="dep-nb" when="init">
254 What other NetBeans projects and modules does this one depend on?
256 Depending on other NetBeans projects influnces the ability of
257 users of your work to customize their own branded version of
258 NetBeans by enabling and disabling some modules. Too
259 much dependencies restrict this kind of customization. If that
260 is your case, then you may want to split your functionality into
261 pieces of autoload, eager and regular modules which can be
262 enabled independently. Usually the answer to this question
263 is generated from your <code>project.xml</code> file, but
264 if it is not guessed correctly, you can suppress it by
265 specifying <defaultanswer generate="none"/> and
266 write here your own. Please describe such projects as imported APIs using
267 the <code><api name="identification" type="import or export" category="stable" url="where is the description" /></code>.
268 By doing this information gets listed in the summary page of your
274 <defaultanswer generate='here' />
280 <question id="dep-non-nb" when="init">
281 What other projects outside NetBeans does this one depend on?
284 Depending on 3rd party libraries is always problematic,
285 especially if they are not open source, as that complicates
286 the licensing scheme of NetBeans. Please enumerate your
287 external dependencies here, so it is correctly understood since
288 the begining what are the legal implications of your project.
289 Also please note that
290 some non-NetBeans projects are packaged as NetBeans modules
291 (see <a href="http://libs.netbeans.org/">libraries</a>) and
292 it is preferred to use this approach when more modules may
293 depend and share such third-party libraries.
297 <answer id="dep-non-nb">
299 XXX no answer for dep-non-nb
306 <question id="dep-platform" when="init">
307 On which platforms does your module run? Does it run in the same
310 If you plan any dependency on OS or any usage of native code,
311 please describe why you are doing so and describe how you envision
312 to enforce the portability of your code.
313 Please note that there is a support for <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html#how-os-specific">OS conditionally
314 enabled modules</a> which together with autoload/eager modules
315 can allow you to enable to provide the best OS aware support
316 on certain OSes while providing compatibility bridge on the not
318 Also please list the supported
319 OSes/HW platforms and mentioned the lovest version of JDK required
320 for your project to run on. Also state whether JRE is enough or
325 <answer id="dep-platform">
327 XXX no answer for dep-platform
334 <question id="deploy-dependencies" when="final">
335 What do other modules need to do to declare a dependency on this one,
336 in addition to or instead of the normal module dependency declaration
337 (e.g. tokens to require)?
339 Provide a sample of the actual lines you would add to a module manifest
340 to declare a dependency, for example OpenIDE-Module-Requires: some.token.
341 If other modules should not depend on this module, or should just use a
342 simple regular module dependency, you can just answer "nothing". If you
343 intentionally expose a semistable API to clients using implementation
344 dependencies, you should mention that here (but there is no need to give
345 an example of usage).
349 <answer id="deploy-dependencies">
351 XXX no answer for deploy-dependencies
358 <question id="deploy-jar" when="impl">
359 Do you deploy just module JAR file(s) or other files as well?
361 Usually a module consist of one JAR file (perhaps with Class-Path
362 extensions) and also a configuration file that enables it. If you
363 have any other files, use
364 <api group="java.io.File" name="yourname" type="export" category="friend">...</api>
365 to define the location, name and stability of your files (of course
366 changing "yourname" and "friend" to suit your needs).
368 If it uses more than one JAR, describe where they are located, how
369 they refer to each other.
370 If it consist of module JAR(s) and other files, please describe
371 what is their purpose, why other files are necessary. Please
372 make sure that installation/uninstallation leaves the system
373 in state as it was before installation.
377 <answer id="deploy-jar">
379 XXX no answer for deploy-jar
386 <question id="deploy-nbm" when="impl">
387 Can you deploy an NBM via the Update Center?
393 <answer id="deploy-nbm">
395 XXX no answer for deploy-nbm
402 <question id="deploy-packages" when="init">
403 Are packages of your module made inaccessible by not declaring them
407 By default NetBeans build harness treats all packages are private.
408 If you export some of them - either as public or friend packages,
409 you should have a reason. If the reason is described elsewhere
410 in this document, you can ignore this question.
414 <answer id="deploy-packages">
416 XXX no answer for deploy-packages
423 <question id="deploy-shared" when="final">
424 Do you need to be installed in the shared location only, or in the user directory only,
425 or can your module be installed anywhere?
427 Installation location shall not matter, if it does explain why.
428 Consider also whether <code>InstalledFileLocator</code> can help.
432 <answer id="deploy-shared">
434 XXX no answer for deploy-shared
441 <question id="exec-ant-tasks" when="impl">
442 Do you define or register any ant tasks that other can use?
445 If you provide an ant task that users can use, you need to be very
446 careful about its syntax and behaviour, as it most likely forms an
447 API for end users and as there is a lot of end users, their reaction
448 when such API gets broken can be pretty strong.
452 <answer id="exec-ant-tasks">
454 XXX no answer for exec-ant-tasks
461 <question id="exec-classloader" when="impl">
462 Does your code create its own class loader(s)?
464 A bit unusual. Please explain why and what for.
468 <answer id="exec-classloader">
470 XXX no answer for exec-classloader
477 <question id="exec-component" when="impl">
478 Is execution of your code influenced by any (string) property
479 of any of your components?
482 Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
483 or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
484 a behavior of some code. This of course forms an interface that should
485 be documented. Also if one depends on some interface that an object
486 implements (<code>component instanceof Runnable</code>) that forms an
491 <answer id="exec-component">
493 XXX no answer for exec-component
500 <question id="exec-introspection" when="impl">
501 Does your module use any kind of runtime type information (<code>instanceof</code>,
502 work with <code>java.lang.Class</code>, etc.)?
504 Check for cases when you have an object of type A and you also
505 expect it to (possibly) be of type B and do some special action. That
506 should be documented. The same applies on operations in meta-level
507 (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
511 <answer id="exec-introspection">
513 XXX no answer for exec-introspection
520 <question id="exec-privateaccess" when="final">
521 Are you aware of any other parts of the system calling some of
522 your methods by reflection?
524 If so, describe the "contract" as an API. Likely private or friend one, but
525 still API and consider rewrite of it.
529 <answer id="exec-privateaccess">
531 XXX no answer for exec-privateaccess
538 <question id="exec-process" when="impl">
539 Do you execute an external process from your module? How do you ensure
540 that the result is the same on different platforms? Do you parse output?
541 Do you depend on result code?
543 If you feed an input, parse the output please declare that as an API.
547 <answer id="exec-process">
549 XXX no answer for exec-process
556 <question id="exec-property" when="impl">
557 Is execution of your code influenced by any environment or
558 Java system (<code>System.getProperty</code>) property?
559 On a similar note, is there something interesting that you
560 pass to <code>java.util.logging.Logger</code>? Or do you observe
563 If there is a property that can change the behavior of your
564 code, somebody will likely use it. You should describe what it does
565 and the <a href="http://openide.netbeans.org/tutorial/api-design.html#life">stability category</a>
566 of this API. You may use
568 <api type="export" group="property" name="id" category="private" url="http://...">
569 description of the property, where it is used, what it influence, etc.
575 <answer id="exec-property">
577 XXX no answer for exec-property
584 <question id="exec-reflection" when="impl">
585 Does your code use Java Reflection to execute other code?
587 This usually indicates a missing or insufficient API in the other
588 part of the system. If the other side is not aware of your dependency
589 this contract can be easily broken.
593 <answer id="exec-reflection">
595 XXX no answer for exec-reflection
602 <question id="exec-threading" when="init">
603 What threading models, if any, does your module adhere to? How the
604 project behaves with respect to threading?
606 Is your API threadsafe? Can it be accessed from any threads or
607 just from some dedicated ones? Any special relation to AWT and
608 its Event Dispatch thread? Also
609 if your module calls foreign APIs which have a specific threading model,
610 indicate how you comply with the requirements for multithreaded access
611 (synchronization, mutexes, etc.) applicable to those APIs.
612 If your module defines any APIs, or has complex internal structures
613 that might be used from multiple threads, declare how you protect
614 data against concurrent access, race conditions, deadlocks, etc.,
615 and whether such rules are enforced by runtime warnings, errors, assertions, etc.
616 Examples: a class might be non-thread-safe (like Java Collections); might
617 be fully thread-safe (internal locking); might require access through a mutex
618 (and may or may not automatically acquire that mutex on behalf of a client method);
619 might be able to run only in the event queue; etc.
620 Also describe when any events are fired: synchronously, asynchronously, etc.
621 Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
625 <answer id="exec-threading">
627 XXX no answer for exec-threading
634 <question id="format-clipboard" when="impl">
635 Which data flavors (if any) does your code read from or insert to
636 the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
639 Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
640 Check your code for overriding these methods.
644 <answer id="format-clipboard">
646 XXX no answer for format-clipboard
653 <question id="format-dnd" when="impl">
654 Which protocols (if any) does your code understand during Drag & Drop?
656 Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>.
657 Check your code for overriding these methods. Btw. if they are not overridden, they
658 by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
662 <answer id="format-dnd">
664 XXX no answer for format-dnd
671 <question id="format-types" when="impl">
672 Which protocols and file formats (if any) does your module read or write on disk,
673 or transmit or receive over the network? Do you generate an ant build script?
674 Can it be edited and modified?
678 Files can be read and written by other programs, modules and users. If they influence
679 your behaviour, make sure you either document the format or claim that it is a private
680 api (using the <api> tag).
684 If you generate an ant build file, this is very likely going to be seen by end users and
685 they will be attempted to edit it. You should be ready for that and provide here a link
686 to documentation that you have for such purposes and also describe how you are going to
687 understand such files during next release, when you (very likely) slightly change the
693 <answer id="format-types">
695 XXX no answer for format-types
702 <question id="lookup-lookup" when="init">
703 Does your module use <code>org.openide.util.Lookup</code>
704 or any similar technology to find any components to communicate with? Which ones?
707 NetBeans is build around a generic registry of services called
708 lookup. It is preferable to use it for registration and discovery
710 <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/lookup/doc-files/index.html">
711 The Solution to Comunication Between Components
712 </a>. If you do not plan to use lookup and insist usage
713 of other solution, then please describe why it is not working for
716 When filling the final version of your arch document, please
717 describe the interfaces you are searching for, where
718 are defined, whether you are searching for just one or more of them,
719 if the order is important, etc. Also classify the stability of such
720 API contract. Use <api group=&lookup& /> tag, so
721 your information gets listed in the summary page of your javadoc.
725 <answer id="lookup-lookup">
727 XXX no answer for lookup-lookup
734 <question id="lookup-register" when="final">
735 Do you register anything into lookup for other code to find?
737 Do you register using layer file or using <code>META-INF/services</code>?
738 Who is supposed to find your component?
742 <answer id="lookup-register">
744 XXX no answer for lookup-register
751 <question id="lookup-remove" when="final">
752 Do you remove entries of other modules from lookup?
754 Why? Of course, that is possible, but it can be dangerous. Is the module
755 your are masking resource from aware of what you are doing?
759 <answer id="lookup-remove">
761 XXX no answer for lookup-remove
768 <question id="perf-exit" when="final">
769 Does your module run any code on exit?
772 <answer id="perf-exit">
774 XXX no answer for perf-exit
781 <question id="perf-huge_dialogs" when="final">
782 Does your module contain any dialogs or wizards with a large number of
783 GUI controls such as combo boxes, lists, trees, or text areas?
786 <answer id="perf-huge_dialogs">
788 XXX no answer for perf-huge_dialogs
795 <question id="perf-limit" when="init">
796 Are there any hard-coded or practical limits in the number or size of
797 elements your code can handle?
799 Most of algorithms have increasing memory and speed complexity
800 with respect to size of data they operate on. What is the critical
801 part of your project that can be seen as a bottleneck with
802 respect to speed or required memory? What are the practical
803 sizes of data you tested your project with? What is your estimate
804 of potential size of data that would cause visible performance
805 problems? Is there some kind of check to detect such situation
806 and prevent "hard" crashes - for example the CloneableEditorSupport
807 checks for size of a file to be opened in editor
808 and if it is larger than 1Mb it shows a dialog giving the
809 user the right to decide - e.g. to cancel or commit suicide.
813 <answer id="perf-limit">
815 XXX no answer for perf-limit
822 <question id="perf-mem" when="final">
823 How much memory does your component consume? Estimate
824 with a relation to the number of windows, etc.
827 <answer id="perf-mem">
829 XXX no answer for perf-mem
836 <question id="perf-menus" when="final">
837 Does your module use dynamically updated context menus, or
838 context-sensitive actions with complicated and slow enablement logic?
840 If you do a lot of tricks when adding actions to regular or context menus, you can significantly
841 slow down display of the menu, even when the user is not using your action. Pay attention to
842 actions you add to the main menu bar, and to context menus of foreign nodes or components. If
843 the action is conditionally enabled, or changes its display dynamically, you need to check the
844 impact on performance. In some cases it may be more appropriate to make a simple action that is
845 always enabled but does more detailed checks in a dialog if it is actually run.
849 <answer id="perf-menus">
851 XXX no answer for perf-menus
858 <question id="perf-progress" when="final">
859 Does your module execute any long-running tasks?
861 <hint>Long running tasks should never block
862 AWT thread as it badly hurts the UI
863 <a href="http://performance.netbeans.org/responsiveness/issues.html">
865 Tasks like connecting over
866 network, computing huge amount of data, compilation
867 be done asynchronously (for example
868 using <code>RequestProcessor</code>), definitively it should
869 not block AWT thread.
873 <answer id="perf-progress">
875 XXX no answer for perf-progress
882 <question id="perf-scale" when="init">
883 Which external criteria influence the performance of your
884 program (size of file in editor, number of files in menu,
885 in source directory, etc.) and how well your code scales?
887 Please include some estimates, there are other more detailed
888 questions to answer in later phases of implementation.
892 <answer id="perf-scale">
894 XXX no answer for perf-scale
901 <question id="perf-spi" when="init">
902 How the performance of the plugged in code will be enforced?
904 If you allow foreign code to be plugged into your own module, how
905 do you enforce that it will behave correctly and quickly and will not
906 negatively influence the performance of your own module?
910 <answer id="perf-spi">
912 XXX no answer for perf-spi
919 <question id="perf-startup" when="final">
920 Does your module run any code on startup?
923 <answer id="perf-startup">
925 XXX no answer for perf-startup
932 <question id="perf-wakeup" when="final">
933 Does any piece of your code wake up periodically and do something
934 even when the system is otherwise idle (no user interaction)?
937 <answer id="perf-wakeup">
939 XXX no answer for perf-wakeup
946 <question id="resources-file" when="final">
947 Does your module use <code>java.io.File</code> directly?
950 NetBeans provide a logical wrapper over plain files called
951 <code>org.openide.filesystems.FileObject</code> that
952 provides uniform access to such resources and is the preferred
953 way that should be used. But of course there can be situations when
954 this is not suitable.
958 <answer id="resources-file">
960 XXX no answer for resources-file
967 <question id="resources-layer" when="final">
968 Does your module provide own layer? Does it create any files or
969 folders in it? What it is trying to communicate by that and with which
973 NetBeans allows automatic and declarative installation of resources
974 by module layers. Module register files into appropriate places
975 and other components use that information to perform their task
976 (build menu, toolbar, window layout, list of templates, set of
981 <answer id="resources-layer">
983 XXX no answer for resources-layer
990 <question id="resources-mask" when="final">
991 Does your module mask/hide/override any resources provided by other modules in
995 If you mask a file provided by another module, you probably depend
996 on that and do not want the other module to (for example) change
997 the file's name. That module shall thus make that file available as an API
998 of some stability category.
1002 <answer id="resources-mask">
1004 XXX no answer for resources-mask
1011 <question id="resources-preferences" when="final">
1012 Does your module uses preferences via Preferences API? Does your module use NbPreferences or
1013 or regular JDK Preferences ? Does it read, write or both ?
1014 Does it share preferences with other modules ? If so, then why ?
1017 <api type="export" group="preferences"
1018 name="preference node name" category="private">
1019 description of individual keys, where it is used, what it
1020 influences, whether the module reads/write it, etc.
1022 Due to XML ID restrictions, rather than /org/netbeans/modules/foo give the "name" as org.netbeans.modules.foo.
1023 Note that if you use NbPreferences this name will then be the same as the code name base of the module.
1027 <answer id="resources-preferences">
1029 XXX no answer for resources-preferences
1036 <question id="resources-read" when="final">
1037 Does your module read any resources from layers? For what purpose?
1040 As this is some kind of intermodule dependency, it is a kind of API.
1041 Please describe it and classify according to
1042 <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
1043 common stability categories</a>.
1047 <answer id="resources-read">
1049 XXX no answer for resources-read
1056 <question id="security-grant" when="final">
1057 Does your code grant additional rights to some other code?
1058 <hint>Avoid using a class loader that adds extra
1059 permissions to loaded code unless really necessary.
1060 Also note that your API implementation
1061 can also expose unneeded permissions to enemy code by
1062 calling AccessController.doPrivileged().</hint>
1065 <answer id="security-grant">
1067 XXX no answer for security-grant
1074 <question id="security-policy" when="final">
1075 Does your functionality require modifications to the standard policy file?
1076 <hint>Your code might pass control to third-party code not
1077 coming from trusted domains. This could be code downloaded over the
1078 network or code coming from libraries that are not bundled
1079 with NetBeans. Which permissions need to be granted to which domains?</hint>
1082 <answer id="security-policy">
1084 XXX no answer for security-policy