1.1 --- a/sandbox/java.hints/spi.java.hints/arch.xml Mon Dec 19 11:37:36 2016 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1115 +0,0 @@
1.4 -<?xml version="1.0" encoding="UTF-8"?>
1.5 -<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
1.6 - <!ENTITY api-questions SYSTEM "../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
1.7 -]>
1.8 -
1.9 -<api-answers
1.10 - question-version="1.29"
1.11 - author="jlahoda@netbeans.org"
1.12 ->
1.13 -
1.14 - &api-questions;
1.15 -
1.16 -
1.17 -<!--
1.18 - <question id="arch-overall" when="init">
1.19 - Describe the overall architecture.
1.20 - <hint>
1.21 - What will be API for
1.22 - <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi">
1.23 - clients and what support API</a>?
1.24 - What parts will be pluggable?
1.25 - How will plug-ins be registered? Please use <code><api type="export"/></code>
1.26 - to describe your general APIs and specify their
1.27 - <a href="http://openide.netbeans.org/tutorial/api-design.html#category-private">
1.28 - stability categories</a>.
1.29 - If possible please provide simple diagrams.
1.30 - </hint>
1.31 - </question>
1.32 --->
1.33 - <answer id="arch-overall">
1.34 - <p>
1.35 - <api type="export" category="devel" group="java" name="spi.java.hints">
1.36 - SPI to create custom Java hints, including code smell warnings, productivity tips, etc.
1.37 - Please see the Use Cases section for a guide on how to use this SPI.
1.38 - </api>
1.39 - </p>
1.40 - </answer>
1.41 -
1.42 -
1.43 -
1.44 -<!--
1.45 - <question id="arch-quality" when="init">
1.46 - How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html">quality</a>
1.47 - of your code be tested and
1.48 - how are future regressions going to be prevented?
1.49 - <hint>
1.50 - What kind of testing do
1.51 - you want to use? How much functionality, in which areas,
1.52 - should be covered by the tests? How you find out that your
1.53 - project was successful?
1.54 - </hint>
1.55 - </question>
1.56 --->
1.57 - <answer id="arch-quality">
1.58 - <p>
1.59 - XXX no answer for arch-quality
1.60 - </p>
1.61 - </answer>
1.62 -
1.63 -
1.64 -
1.65 -<!--
1.66 - <question id="arch-time" when="init">
1.67 - What are the time estimates of the work?
1.68 - <hint>
1.69 - Please express your estimates of how long the design, implementation,
1.70 - stabilization are likely to last. How many people will be needed to
1.71 - implement this and what is the expected milestone by which the work should be
1.72 - ready?
1.73 - </hint>
1.74 - </question>
1.75 --->
1.76 - <answer id="arch-time">
1.77 - <p>
1.78 - XXX no answer for arch-time
1.79 - </p>
1.80 - </answer>
1.81 -
1.82 -
1.83 -
1.84 -<!--
1.85 - <question id="arch-usecases" when="init">
1.86 - <hint>
1.87 - Content of this answer will be displayed as part of page at
1.88 - http://www.netbeans.org/download/dev/javadoc/usecases.html
1.89 - You can use tags <usecase name="name> regular html description </usecase>
1.90 - and if you want to use an URL you can prefix if with @TOP@ to begin
1.91 - at the root of your javadoc
1.92 - </hint>
1.93 -
1.94 - Describe the main <a href="http://openide.netbeans.org/tutorial/api-design.html#usecase">
1.95 - use cases</a> of the new API. Who will use it under
1.96 - what circumstances? What kind of code would typically need to be written
1.97 - to use the module?
1.98 - </question>
1.99 --->
1.100 - <answer id="arch-usecases">
1.101 - <p>
1.102 - <usecase id="creating" name="Creating a new Java Hint">
1.103 - Simple way to create a new Java hint is as follows:
1.104 - <ul>
1.105 - <li>Create a new class, annotate it with the <a href="@TOP@/org/netbeans/spi/java/hints/Hint.html">@Hint</a>
1.106 - annotation to it.</li>
1.107 - <li>Create a <code>public static ErrorDescription hint(HintContext ctx) {}</code> method in the
1.108 - class. Annotate the method either with the <a href="@TOP@/org/netbeans/spi/java/hints/TriggerPattern.html">@TriggerPattern</a>
1.109 - annotation (strongly recommended), or with the <a href="@TOP@/org/netbeans/spi/java/hints/TriggerTreeKind.html">@TriggerTreeKind</a>.
1.110 - This method will be called when for parts of the code that match the given pattern, of for trees of the specified kinds.</li>
1.111 - <li>Perform whatever checks necessary to find out whether a warning should be produced at the given place, and produce the ErrorDescription if needed.</li>
1.112 - </ul>
1.113 - <br/>
1.114 - Tips:
1.115 - <ul>
1.116 - <li>Always use the java.hints' <a href="@TOP@/org/netbeans/spi/java/hints/ErrorDescriptionFactory.html">ErrorDescriptionFactory</a> to produce the resulting ErrorDescription.</li>
1.117 - <li>Never try to produce a custom suppress warnings "fix". Specify suppress warnings keys in the @Hint annotation.</li>
1.118 - <li>If an automated transformation is to be prodived from your hint, subclass <a href="@TOP@/org/netbeans/spi/java/hints/JavaFix.html">JavaFix</a> and
1.119 - use its <code>toEditorFix()</code> method to get the <code>Fix</code>, if the transformation is going to be used inside Inspect&Transform.
1.120 - </li>
1.121 - <li>The name of the method is arbitrary, one hint can consist of more that one "triggered" method.</li>
1.122 - </ul>
1.123 - </usecase>
1.124 - <usecase id="no-class" name="Creating a new Java Hint Without a Class">
1.125 - For simple hints, it is possible to annotate the hint method with the <a href="@TOP@/org/netbeans/spi/java/hints/Hint.html">@Hint</a> annotation.
1.126 - The hint then consists of this sole method. Any number of such hints may be created in a single class.
1.127 - </usecase>
1.128 - <usecase id="testing" name="Creating a Tests for the Newly Created Java Hint">
1.129 - Creating automated tests for the hints is simple: create a test class, and use
1.130 - <a href="@TOP@/../org-netbeans-modules-java-hints-test/org/netbeans/modules/java/hints/test/api/HintTest.html">HintTest</a>
1.131 - to setup the test, run the hint and verify that its outcomes are correct.
1.132 - The tests automatically run with <code>test</code> branding, so create <code>Bundle_test.properties</code>, and add
1.133 - bundle keys into it for ErrorDescription and Fix display names, to isolate the test from changes in the production
1.134 - <code>Bundle.properties</code>.
1.135 - </usecase>
1.136 - <usecase id="adding-options" name="Adding options to a Java Hint">
1.137 - To add a simple boolean option to your hint, use <a href="@TOP@/org/netbeans/spi/java/hints/BooleanOption.html">@BooleanOption</a>.
1.138 - </usecase>
1.139 - </p>
1.140 - </answer>
1.141 -
1.142 -
1.143 -
1.144 -<!--
1.145 - <question id="arch-what" when="init">
1.146 - What is this project good for?
1.147 - <hint>
1.148 - Please provide here a few lines describing the project,
1.149 - what problem it should solve, provide links to documentation,
1.150 - specifications, etc.
1.151 - </hint>
1.152 - </question>
1.153 --->
1.154 - <answer id="arch-what">
1.155 - <p>
1.156 - XXX no answer for arch-what
1.157 - </p>
1.158 - </answer>
1.159 -
1.160 -
1.161 -
1.162 -<!--
1.163 - <question id="arch-where" when="impl">
1.164 - Where one can find sources for your module?
1.165 - <hint>
1.166 - Please provide link to the Hg web client at
1.167 - http://hg.netbeans.org/
1.168 - or just use tag defaultanswer generate='here'
1.169 - </hint>
1.170 - </question>
1.171 --->
1.172 - <answer id="arch-where">
1.173 - <defaultanswer generate='here' />
1.174 - </answer>
1.175 -
1.176 -
1.177 -
1.178 -<!--
1.179 - <question id="compat-deprecation" when="init">
1.180 - How the introduction of your project influences functionality
1.181 - provided by previous version of the product?
1.182 - <hint>
1.183 - If you are planning to deprecate/remove/change any existing APIs,
1.184 - list them here accompanied with the reason explaining why you
1.185 - are doing so.
1.186 - </hint>
1.187 - </question>
1.188 --->
1.189 - <answer id="compat-deprecation">
1.190 - <p>
1.191 - XXX no answer for compat-deprecation
1.192 - </p>
1.193 - </answer>
1.194 -
1.195 -
1.196 -
1.197 -<!--
1.198 - <question id="compat-i18n" when="impl">
1.199 - Is your module correctly internationalized?
1.200 - <hint>
1.201 - Correct internationalization means that it obeys instructions
1.202 - at <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/i18n-branding.html">
1.203 - NetBeans I18N pages</a>.
1.204 - </hint>
1.205 - </question>
1.206 --->
1.207 - <answer id="compat-i18n">
1.208 - <p>
1.209 - XXX no answer for compat-i18n
1.210 - </p>
1.211 - </answer>
1.212 -
1.213 -
1.214 -
1.215 -<!--
1.216 - <question id="compat-standards" when="init">
1.217 - Does the module implement or define any standards? Is the
1.218 - implementation exact or does it deviate somehow?
1.219 - </question>
1.220 --->
1.221 - <answer id="compat-standards">
1.222 - <p>
1.223 - XXX no answer for compat-standards
1.224 - </p>
1.225 - </answer>
1.226 -
1.227 -
1.228 -
1.229 -<!--
1.230 - <question id="compat-version" when="impl">
1.231 - Can your module coexist with earlier and future
1.232 - versions of itself? Can you correctly read all old settings? Will future
1.233 - versions be able to read your current settings? Can you read
1.234 - or politely ignore settings stored by a future version?
1.235 -
1.236 - <hint>
1.237 - Very helpful for reading settings is to store version number
1.238 - there, so future versions can decide whether how to read/convert
1.239 - the settings and older versions can ignore the new ones.
1.240 - </hint>
1.241 - </question>
1.242 --->
1.243 - <answer id="compat-version">
1.244 - <p>
1.245 - XXX no answer for compat-version
1.246 - </p>
1.247 - </answer>
1.248 -
1.249 -
1.250 -
1.251 -<!--
1.252 - <question id="dep-jre" when="final">
1.253 - Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
1.254 - <hint>
1.255 - It is expected that if your module runs on 1.x that it will run
1.256 - on 1.x+1 if no, state that please. Also describe here cases where
1.257 - you run different code on different versions of JRE and why.
1.258 - </hint>
1.259 - </question>
1.260 --->
1.261 - <answer id="dep-jre">
1.262 - <p>
1.263 - XXX no answer for dep-jre
1.264 - </p>
1.265 - </answer>
1.266 -
1.267 -
1.268 -
1.269 -<!--
1.270 - <question id="dep-jrejdk" when="final">
1.271 - Do you require the JDK or is the JRE enough?
1.272 - </question>
1.273 --->
1.274 - <answer id="dep-jrejdk">
1.275 - <p>
1.276 - XXX no answer for dep-jrejdk
1.277 - </p>
1.278 - </answer>
1.279 -
1.280 -
1.281 -
1.282 -<!--
1.283 - <question id="dep-nb" when="init">
1.284 - What other NetBeans projects and modules does this one depend on?
1.285 - <hint>
1.286 - Depending on other NetBeans projects influnces the ability of
1.287 - users of your work to customize their own branded version of
1.288 - NetBeans by enabling and disabling some modules. Too
1.289 - much dependencies restrict this kind of customization. If that
1.290 - is your case, then you may want to split your functionality into
1.291 - pieces of autoload, eager and regular modules which can be
1.292 - enabled independently. Usually the answer to this question
1.293 - is generated from your <code>project.xml</code> file, but
1.294 - if it is not guessed correctly, you can suppress it by
1.295 - specifying <defaultanswer generate="none"/> and
1.296 - write here your own. Please describe such projects as imported APIs using
1.297 - the <code><api name="identification" type="import or export" category="stable" url="where is the description" /></code>.
1.298 - By doing this information gets listed in the summary page of your
1.299 - javadoc.
1.300 - </hint>
1.301 - </question>
1.302 --->
1.303 - <answer id="dep-nb">
1.304 - <defaultanswer generate='here' />
1.305 - </answer>
1.306 -
1.307 -
1.308 -
1.309 -<!--
1.310 - <question id="dep-non-nb" when="init">
1.311 - What other projects outside NetBeans does this one depend on?
1.312 -
1.313 - <hint>
1.314 - Depending on 3rd party libraries is always problematic,
1.315 - especially if they are not open source, as that complicates
1.316 - the licensing scheme of NetBeans. Please enumerate your
1.317 - external dependencies here, so it is correctly understood since
1.318 - the begining what are the legal implications of your project.
1.319 - Also please note that
1.320 - some non-NetBeans projects are packaged as NetBeans modules
1.321 - (see <a href="http://libs.netbeans.org/">libraries</a>) and
1.322 - it is preferred to use this approach when more modules may
1.323 - depend and share such third-party libraries.
1.324 - </hint>
1.325 - </question>
1.326 --->
1.327 - <answer id="dep-non-nb">
1.328 - <p>
1.329 - XXX no answer for dep-non-nb
1.330 - </p>
1.331 - </answer>
1.332 -
1.333 -
1.334 -
1.335 -<!--
1.336 - <question id="dep-platform" when="init">
1.337 - On which platforms does your module run? Does it run in the same
1.338 - way on each?
1.339 - <hint>
1.340 - If you plan any dependency on OS or any usage of native code,
1.341 - please describe why you are doing so and describe how you envision
1.342 - to enforce the portability of your code.
1.343 - 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
1.344 - enabled modules</a> which together with autoload/eager modules
1.345 - can allow you to enable to provide the best OS aware support
1.346 - on certain OSes while providing compatibility bridge on the not
1.347 - supported ones.
1.348 - Also please list the supported
1.349 - OSes/HW platforms and mentioned the lovest version of JDK required
1.350 - for your project to run on. Also state whether JRE is enough or
1.351 - you really need JDK.
1.352 - </hint>
1.353 - </question>
1.354 --->
1.355 - <answer id="dep-platform">
1.356 - <p>
1.357 - XXX no answer for dep-platform
1.358 - </p>
1.359 - </answer>
1.360 -
1.361 -
1.362 -
1.363 -<!--
1.364 - <question id="deploy-dependencies" when="final">
1.365 - What do other modules need to do to declare a dependency on this one,
1.366 - in addition to or instead of the normal module dependency declaration
1.367 - (e.g. tokens to require)?
1.368 - <hint>
1.369 - Provide a sample of the actual lines you would add to a module manifest
1.370 - to declare a dependency, for example OpenIDE-Module-Requires: some.token.
1.371 - If other modules should not depend on this module, or should just use a
1.372 - simple regular module dependency, you can just answer "nothing". If you
1.373 - intentionally expose a semistable API to clients using implementation
1.374 - dependencies, you should mention that here (but there is no need to give
1.375 - an example of usage).
1.376 - </hint>
1.377 - </question>
1.378 --->
1.379 - <answer id="deploy-dependencies">
1.380 - <p>
1.381 - XXX no answer for deploy-dependencies
1.382 - </p>
1.383 - </answer>
1.384 -
1.385 -
1.386 -
1.387 -<!--
1.388 - <question id="deploy-jar" when="impl">
1.389 - Do you deploy just module JAR file(s) or other files as well?
1.390 - <hint>
1.391 - Usually a module consist of one JAR file (perhaps with Class-Path
1.392 - extensions) and also a configuration file that enables it. If you
1.393 - have any other files, use
1.394 - <api group="java.io.File" name="yourname" type="export" category="friend">...</api>
1.395 - to define the location, name and stability of your files (of course
1.396 - changing "yourname" and "friend" to suit your needs).
1.397 -
1.398 - If it uses more than one JAR, describe where they are located, how
1.399 - they refer to each other.
1.400 - If it consist of module JAR(s) and other files, please describe
1.401 - what is their purpose, why other files are necessary. Please
1.402 - make sure that installation/uninstallation leaves the system
1.403 - in state as it was before installation.
1.404 - </hint>
1.405 - </question>
1.406 --->
1.407 - <answer id="deploy-jar">
1.408 - <p>
1.409 - XXX no answer for deploy-jar
1.410 - </p>
1.411 - </answer>
1.412 -
1.413 -
1.414 -
1.415 -<!--
1.416 - <question id="deploy-nbm" when="impl">
1.417 - Can you deploy an NBM via the Update Center?
1.418 - <hint>
1.419 - If not why?
1.420 - </hint>
1.421 - </question>
1.422 --->
1.423 - <answer id="deploy-nbm">
1.424 - <p>
1.425 - XXX no answer for deploy-nbm
1.426 - </p>
1.427 - </answer>
1.428 -
1.429 -
1.430 -
1.431 -<!--
1.432 - <question id="deploy-packages" when="init">
1.433 - Are packages of your module made inaccessible by not declaring them
1.434 - public?
1.435 -
1.436 - <hint>
1.437 - By default NetBeans build harness treats all packages are private.
1.438 - If you export some of them - either as public or friend packages,
1.439 - you should have a reason. If the reason is described elsewhere
1.440 - in this document, you can ignore this question.
1.441 - </hint>
1.442 - </question>
1.443 --->
1.444 - <answer id="deploy-packages">
1.445 - <p>
1.446 - XXX no answer for deploy-packages
1.447 - </p>
1.448 - </answer>
1.449 -
1.450 -
1.451 -
1.452 -<!--
1.453 - <question id="deploy-shared" when="final">
1.454 - Do you need to be installed in the shared location only, or in the user directory only,
1.455 - or can your module be installed anywhere?
1.456 - <hint>
1.457 - Installation location shall not matter, if it does explain why.
1.458 - Consider also whether <code>InstalledFileLocator</code> can help.
1.459 - </hint>
1.460 - </question>
1.461 --->
1.462 - <answer id="deploy-shared">
1.463 - <p>
1.464 - XXX no answer for deploy-shared
1.465 - </p>
1.466 - </answer>
1.467 -
1.468 -
1.469 -
1.470 -<!--
1.471 - <question id="exec-ant-tasks" when="impl">
1.472 - Do you define or register any ant tasks that other can use?
1.473 -
1.474 - <hint>
1.475 - If you provide an ant task that users can use, you need to be very
1.476 - careful about its syntax and behaviour, as it most likely forms an
1.477 - API for end users and as there is a lot of end users, their reaction
1.478 - when such API gets broken can be pretty strong.
1.479 - </hint>
1.480 - </question>
1.481 --->
1.482 - <answer id="exec-ant-tasks">
1.483 - <p>
1.484 - XXX no answer for exec-ant-tasks
1.485 - </p>
1.486 - </answer>
1.487 -
1.488 -
1.489 -
1.490 -<!--
1.491 - <question id="exec-classloader" when="impl">
1.492 - Does your code create its own class loader(s)?
1.493 - <hint>
1.494 - A bit unusual. Please explain why and what for.
1.495 - </hint>
1.496 - </question>
1.497 --->
1.498 - <answer id="exec-classloader">
1.499 - <p>
1.500 - XXX no answer for exec-classloader
1.501 - </p>
1.502 - </answer>
1.503 -
1.504 -
1.505 -
1.506 -<!--
1.507 - <question id="exec-component" when="impl">
1.508 - Is execution of your code influenced by any (string) property
1.509 - of any of your components?
1.510 -
1.511 - <hint>
1.512 - Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
1.513 - or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
1.514 - a behavior of some code. This of course forms an interface that should
1.515 - be documented. Also if one depends on some interface that an object
1.516 - implements (<code>component instanceof Runnable</code>) that forms an
1.517 - API as well.
1.518 - </hint>
1.519 - </question>
1.520 --->
1.521 - <answer id="exec-component">
1.522 - <p>
1.523 - XXX no answer for exec-component
1.524 - </p>
1.525 - </answer>
1.526 -
1.527 -
1.528 -
1.529 -<!--
1.530 - <question id="exec-introspection" when="impl">
1.531 - Does your module use any kind of runtime type information (<code>instanceof</code>,
1.532 - work with <code>java.lang.Class</code>, etc.)?
1.533 - <hint>
1.534 - Check for cases when you have an object of type A and you also
1.535 - expect it to (possibly) be of type B and do some special action. That
1.536 - should be documented. The same applies on operations in meta-level
1.537 - (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
1.538 - </hint>
1.539 - </question>
1.540 --->
1.541 - <answer id="exec-introspection">
1.542 - <p>
1.543 - XXX no answer for exec-introspection
1.544 - </p>
1.545 - </answer>
1.546 -
1.547 -
1.548 -
1.549 -<!--
1.550 - <question id="exec-privateaccess" when="final">
1.551 - Are you aware of any other parts of the system calling some of
1.552 - your methods by reflection?
1.553 - <hint>
1.554 - If so, describe the "contract" as an API. Likely private or friend one, but
1.555 - still API and consider rewrite of it.
1.556 - </hint>
1.557 - </question>
1.558 --->
1.559 - <answer id="exec-privateaccess">
1.560 - <p>
1.561 - XXX no answer for exec-privateaccess
1.562 - </p>
1.563 - </answer>
1.564 -
1.565 -
1.566 -
1.567 -<!--
1.568 - <question id="exec-process" when="impl">
1.569 - Do you execute an external process from your module? How do you ensure
1.570 - that the result is the same on different platforms? Do you parse output?
1.571 - Do you depend on result code?
1.572 - <hint>
1.573 - If you feed an input, parse the output please declare that as an API.
1.574 - </hint>
1.575 - </question>
1.576 --->
1.577 - <answer id="exec-process">
1.578 - <p>
1.579 - XXX no answer for exec-process
1.580 - </p>
1.581 - </answer>
1.582 -
1.583 -
1.584 -
1.585 -<!--
1.586 - <question id="exec-property" when="impl">
1.587 - Is execution of your code influenced by any environment or
1.588 - Java system (<code>System.getProperty</code>) property?
1.589 - On a similar note, is there something interesting that you
1.590 - pass to <code>java.util.logging.Logger</code>? Or do you observe
1.591 - what others log?
1.592 - <hint>
1.593 - If there is a property that can change the behavior of your
1.594 - code, somebody will likely use it. You should describe what it does
1.595 - and the <a href="http://openide.netbeans.org/tutorial/api-design.html#life">stability category</a>
1.596 - of this API. You may use
1.597 - <pre>
1.598 - <api type="export" group="property" name="id" category="private" url="http://...">
1.599 - description of the property, where it is used, what it influence, etc.
1.600 - </api>
1.601 - </pre>
1.602 - </hint>
1.603 - </question>
1.604 --->
1.605 - <answer id="exec-property">
1.606 - <p>
1.607 - XXX no answer for exec-property
1.608 - </p>
1.609 - </answer>
1.610 -
1.611 -
1.612 -
1.613 -<!--
1.614 - <question id="exec-reflection" when="impl">
1.615 - Does your code use Java Reflection to execute other code?
1.616 - <hint>
1.617 - This usually indicates a missing or insufficient API in the other
1.618 - part of the system. If the other side is not aware of your dependency
1.619 - this contract can be easily broken.
1.620 - </hint>
1.621 - </question>
1.622 --->
1.623 - <answer id="exec-reflection">
1.624 - <p>
1.625 - XXX no answer for exec-reflection
1.626 - </p>
1.627 - </answer>
1.628 -
1.629 -
1.630 -
1.631 -<!--
1.632 - <question id="exec-threading" when="init">
1.633 - What threading models, if any, does your module adhere to? How the
1.634 - project behaves with respect to threading?
1.635 - <hint>
1.636 - Is your API threadsafe? Can it be accessed from any threads or
1.637 - just from some dedicated ones? Any special relation to AWT and
1.638 - its Event Dispatch thread? Also
1.639 - if your module calls foreign APIs which have a specific threading model,
1.640 - indicate how you comply with the requirements for multithreaded access
1.641 - (synchronization, mutexes, etc.) applicable to those APIs.
1.642 - If your module defines any APIs, or has complex internal structures
1.643 - that might be used from multiple threads, declare how you protect
1.644 - data against concurrent access, race conditions, deadlocks, etc.,
1.645 - and whether such rules are enforced by runtime warnings, errors, assertions, etc.
1.646 - Examples: a class might be non-thread-safe (like Java Collections); might
1.647 - be fully thread-safe (internal locking); might require access through a mutex
1.648 - (and may or may not automatically acquire that mutex on behalf of a client method);
1.649 - might be able to run only in the event queue; etc.
1.650 - Also describe when any events are fired: synchronously, asynchronously, etc.
1.651 - Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
1.652 - </hint>
1.653 - </question>
1.654 --->
1.655 - <answer id="exec-threading">
1.656 - <p>
1.657 - XXX no answer for exec-threading
1.658 - </p>
1.659 - </answer>
1.660 -
1.661 -
1.662 -
1.663 -<!--
1.664 - <question id="format-clipboard" when="impl">
1.665 - Which data flavors (if any) does your code read from or insert to
1.666 - the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
1.667 -
1.668 - <hint>
1.669 - Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
1.670 - Check your code for overriding these methods.
1.671 - </hint>
1.672 - </question>
1.673 --->
1.674 - <answer id="format-clipboard">
1.675 - <p>
1.676 - XXX no answer for format-clipboard
1.677 - </p>
1.678 - </answer>
1.679 -
1.680 -
1.681 -
1.682 -<!--
1.683 - <question id="format-dnd" when="impl">
1.684 - Which protocols (if any) does your code understand during Drag & Drop?
1.685 - <hint>
1.686 - Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>.
1.687 - Check your code for overriding these methods. Btw. if they are not overridden, they
1.688 - by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
1.689 - </hint>
1.690 - </question>
1.691 --->
1.692 - <answer id="format-dnd">
1.693 - <p>
1.694 - XXX no answer for format-dnd
1.695 - </p>
1.696 - </answer>
1.697 -
1.698 -
1.699 -
1.700 -<!--
1.701 - <question id="format-types" when="impl">
1.702 - Which protocols and file formats (if any) does your module read or write on disk,
1.703 - or transmit or receive over the network? Do you generate an ant build script?
1.704 - Can it be edited and modified?
1.705 -
1.706 - <hint>
1.707 - <p>
1.708 - Files can be read and written by other programs, modules and users. If they influence
1.709 - your behaviour, make sure you either document the format or claim that it is a private
1.710 - api (using the <api> tag).
1.711 - </p>
1.712 -
1.713 - <p>
1.714 - If you generate an ant build file, this is very likely going to be seen by end users and
1.715 - they will be attempted to edit it. You should be ready for that and provide here a link
1.716 - to documentation that you have for such purposes and also describe how you are going to
1.717 - understand such files during next release, when you (very likely) slightly change the
1.718 - format.
1.719 - </p>
1.720 - </hint>
1.721 - </question>
1.722 --->
1.723 - <answer id="format-types">
1.724 - <p>
1.725 - XXX no answer for format-types
1.726 - </p>
1.727 - </answer>
1.728 -
1.729 -
1.730 -
1.731 -<!--
1.732 - <question id="lookup-lookup" when="init">
1.733 - Does your module use <code>org.openide.util.Lookup</code>
1.734 - or any similar technology to find any components to communicate with? Which ones?
1.735 -
1.736 - <hint>
1.737 - NetBeans is build around a generic registry of services called
1.738 - lookup. It is preferable to use it for registration and discovery
1.739 - if possible. See
1.740 - <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/lookup/doc-files/index.html">
1.741 - The Solution to Comunication Between Components
1.742 - </a>. If you do not plan to use lookup and insist usage
1.743 - of other solution, then please describe why it is not working for
1.744 - you.
1.745 - <br/>
1.746 - When filling the final version of your arch document, please
1.747 - describe the interfaces you are searching for, where
1.748 - are defined, whether you are searching for just one or more of them,
1.749 - if the order is important, etc. Also classify the stability of such
1.750 - API contract. Use <api group=&lookup& /> tag, so
1.751 - your information gets listed in the summary page of your javadoc.
1.752 - </hint>
1.753 - </question>
1.754 --->
1.755 - <answer id="lookup-lookup">
1.756 - <p>
1.757 - XXX no answer for lookup-lookup
1.758 - </p>
1.759 - </answer>
1.760 -
1.761 -
1.762 -
1.763 -<!--
1.764 - <question id="lookup-register" when="final">
1.765 - Do you register anything into lookup for other code to find?
1.766 - <hint>
1.767 - Do you register using layer file or using a declarative annotation such as <code>@ServiceProvider</code>?
1.768 - Who is supposed to find your component?
1.769 - </hint>
1.770 - </question>
1.771 --->
1.772 - <answer id="lookup-register">
1.773 - <p>
1.774 - XXX no answer for lookup-register
1.775 - </p>
1.776 - </answer>
1.777 -
1.778 -
1.779 -
1.780 -<!--
1.781 - <question id="lookup-remove" when="final">
1.782 - Do you remove entries of other modules from lookup?
1.783 - <hint>
1.784 - Why? Of course, that is possible, but it can be dangerous. Is the module
1.785 - your are masking resource from aware of what you are doing?
1.786 - </hint>
1.787 - </question>
1.788 --->
1.789 - <answer id="lookup-remove">
1.790 - <p>
1.791 - XXX no answer for lookup-remove
1.792 - </p>
1.793 - </answer>
1.794 -
1.795 -
1.796 -
1.797 -<!--
1.798 - <question id="perf-exit" when="final">
1.799 - Does your module run any code on exit?
1.800 - </question>
1.801 --->
1.802 - <answer id="perf-exit">
1.803 - <p>
1.804 - XXX no answer for perf-exit
1.805 - </p>
1.806 - </answer>
1.807 -
1.808 -
1.809 -
1.810 -<!--
1.811 - <question id="perf-huge_dialogs" when="final">
1.812 - Does your module contain any dialogs or wizards with a large number of
1.813 - GUI controls such as combo boxes, lists, trees, or text areas?
1.814 - </question>
1.815 --->
1.816 - <answer id="perf-huge_dialogs">
1.817 - <p>
1.818 - XXX no answer for perf-huge_dialogs
1.819 - </p>
1.820 - </answer>
1.821 -
1.822 -
1.823 -
1.824 -<!--
1.825 - <question id="perf-limit" when="init">
1.826 - Are there any hard-coded or practical limits in the number or size of
1.827 - elements your code can handle?
1.828 - <hint>
1.829 - Most of algorithms have increasing memory and speed complexity
1.830 - with respect to size of data they operate on. What is the critical
1.831 - part of your project that can be seen as a bottleneck with
1.832 - respect to speed or required memory? What are the practical
1.833 - sizes of data you tested your project with? What is your estimate
1.834 - of potential size of data that would cause visible performance
1.835 - problems? Is there some kind of check to detect such situation
1.836 - and prevent "hard" crashes - for example the CloneableEditorSupport
1.837 - checks for size of a file to be opened in editor
1.838 - and if it is larger than 1Mb it shows a dialog giving the
1.839 - user the right to decide - e.g. to cancel or commit suicide.
1.840 - </hint>
1.841 - </question>
1.842 --->
1.843 - <answer id="perf-limit">
1.844 - <p>
1.845 - XXX no answer for perf-limit
1.846 - </p>
1.847 - </answer>
1.848 -
1.849 -
1.850 -
1.851 -<!--
1.852 - <question id="perf-mem" when="final">
1.853 - How much memory does your component consume? Estimate
1.854 - with a relation to the number of windows, etc.
1.855 - </question>
1.856 --->
1.857 - <answer id="perf-mem">
1.858 - <p>
1.859 - XXX no answer for perf-mem
1.860 - </p>
1.861 - </answer>
1.862 -
1.863 -
1.864 -
1.865 -<!--
1.866 - <question id="perf-menus" when="final">
1.867 - Does your module use dynamically updated context menus, or
1.868 - context-sensitive actions with complicated and slow enablement logic?
1.869 - <hint>
1.870 - If you do a lot of tricks when adding actions to regular or context menus, you can significantly
1.871 - slow down display of the menu, even when the user is not using your action. Pay attention to
1.872 - actions you add to the main menu bar, and to context menus of foreign nodes or components. If
1.873 - the action is conditionally enabled, or changes its display dynamically, you need to check the
1.874 - impact on performance. In some cases it may be more appropriate to make a simple action that is
1.875 - always enabled but does more detailed checks in a dialog if it is actually run.
1.876 - </hint>
1.877 - </question>
1.878 --->
1.879 - <answer id="perf-menus">
1.880 - <p>
1.881 - XXX no answer for perf-menus
1.882 - </p>
1.883 - </answer>
1.884 -
1.885 -
1.886 -
1.887 -<!--
1.888 - <question id="perf-progress" when="final">
1.889 - Does your module execute any long-running tasks?
1.890 -
1.891 - <hint>Long running tasks should never block
1.892 - AWT thread as it badly hurts the UI
1.893 - <a href="http://performance.netbeans.org/responsiveness/issues.html">
1.894 - responsiveness</a>.
1.895 - Tasks like connecting over
1.896 - network, computing huge amount of data, compilation
1.897 - be done asynchronously (for example
1.898 - using <code>RequestProcessor</code>), definitively it should
1.899 - not block AWT thread.
1.900 - </hint>
1.901 - </question>
1.902 --->
1.903 - <answer id="perf-progress">
1.904 - <p>
1.905 - XXX no answer for perf-progress
1.906 - </p>
1.907 - </answer>
1.908 -
1.909 -
1.910 -
1.911 -<!--
1.912 - <question id="perf-scale" when="init">
1.913 - Which external criteria influence the performance of your
1.914 - program (size of file in editor, number of files in menu,
1.915 - in source directory, etc.) and how well your code scales?
1.916 - <hint>
1.917 - Please include some estimates, there are other more detailed
1.918 - questions to answer in later phases of implementation.
1.919 - </hint>
1.920 - </question>
1.921 --->
1.922 - <answer id="perf-scale">
1.923 - <p>
1.924 - XXX no answer for perf-scale
1.925 - </p>
1.926 - </answer>
1.927 -
1.928 -
1.929 -
1.930 -<!--
1.931 - <question id="perf-spi" when="init">
1.932 - How the performance of the plugged in code will be enforced?
1.933 - <hint>
1.934 - If you allow foreign code to be plugged into your own module, how
1.935 - do you enforce that it will behave correctly and quickly and will not
1.936 - negatively influence the performance of your own module?
1.937 - </hint>
1.938 - </question>
1.939 --->
1.940 - <answer id="perf-spi">
1.941 - <p>
1.942 - XXX no answer for perf-spi
1.943 - </p>
1.944 - </answer>
1.945 -
1.946 -
1.947 -
1.948 -<!--
1.949 - <question id="perf-startup" when="final">
1.950 - Does your module run any code on startup?
1.951 - </question>
1.952 --->
1.953 - <answer id="perf-startup">
1.954 - <p>
1.955 - XXX no answer for perf-startup
1.956 - </p>
1.957 - </answer>
1.958 -
1.959 -
1.960 -
1.961 -<!--
1.962 - <question id="perf-wakeup" when="final">
1.963 - Does any piece of your code wake up periodically and do something
1.964 - even when the system is otherwise idle (no user interaction)?
1.965 - </question>
1.966 --->
1.967 - <answer id="perf-wakeup">
1.968 - <p>
1.969 - XXX no answer for perf-wakeup
1.970 - </p>
1.971 - </answer>
1.972 -
1.973 -
1.974 -
1.975 -<!--
1.976 - <question id="resources-file" when="final">
1.977 - Does your module use <code>java.io.File</code> directly?
1.978 -
1.979 - <hint>
1.980 - NetBeans provide a logical wrapper over plain files called
1.981 - <code>org.openide.filesystems.FileObject</code> that
1.982 - provides uniform access to such resources and is the preferred
1.983 - way that should be used. But of course there can be situations when
1.984 - this is not suitable.
1.985 - </hint>
1.986 - </question>
1.987 --->
1.988 - <answer id="resources-file">
1.989 - <p>
1.990 - XXX no answer for resources-file
1.991 - </p>
1.992 - </answer>
1.993 -
1.994 -
1.995 -
1.996 -<!--
1.997 - <question id="resources-layer" when="final">
1.998 - Does your module provide own layer? Does it create any files or
1.999 - folders in it? What it is trying to communicate by that and with which
1.1000 - components?
1.1001 -
1.1002 - <hint>
1.1003 - NetBeans allows automatic and declarative installation of resources
1.1004 - by module layers. Module register files into appropriate places
1.1005 - and other components use that information to perform their task
1.1006 - (build menu, toolbar, window layout, list of templates, set of
1.1007 - options, etc.).
1.1008 - </hint>
1.1009 - </question>
1.1010 --->
1.1011 - <answer id="resources-layer">
1.1012 - <p>
1.1013 - XXX no answer for resources-layer
1.1014 - </p>
1.1015 - </answer>
1.1016 -
1.1017 -
1.1018 -
1.1019 -<!--
1.1020 - <question id="resources-mask" when="final">
1.1021 - Does your module mask/hide/override any resources provided by other modules in
1.1022 - their layers?
1.1023 -
1.1024 - <hint>
1.1025 - If you mask a file provided by another module, you probably depend
1.1026 - on that and do not want the other module to (for example) change
1.1027 - the file's name. That module shall thus make that file available as an API
1.1028 - of some stability category.
1.1029 - </hint>
1.1030 - </question>
1.1031 --->
1.1032 - <answer id="resources-mask">
1.1033 - <p>
1.1034 - XXX no answer for resources-mask
1.1035 - </p>
1.1036 - </answer>
1.1037 -
1.1038 -
1.1039 -
1.1040 -<!--
1.1041 - <question id="resources-preferences" when="final">
1.1042 - Does your module uses preferences via Preferences API? Does your module use NbPreferences or
1.1043 - or regular JDK Preferences ? Does it read, write or both ?
1.1044 - Does it share preferences with other modules ? If so, then why ?
1.1045 - <hint>
1.1046 - You may use
1.1047 - <api type="export" group="preferences"
1.1048 - name="preference node name" category="private">
1.1049 - description of individual keys, where it is used, what it
1.1050 - influences, whether the module reads/write it, etc.
1.1051 - </api>
1.1052 - Due to XML ID restrictions, rather than /org/netbeans/modules/foo give the "name" as org.netbeans.modules.foo.
1.1053 - Note that if you use NbPreferences this name will then be the same as the code name base of the module.
1.1054 - </hint>
1.1055 - </question>
1.1056 --->
1.1057 - <answer id="resources-preferences">
1.1058 - <p>
1.1059 - XXX no answer for resources-preferences
1.1060 - </p>
1.1061 - </answer>
1.1062 -
1.1063 -
1.1064 -
1.1065 -<!--
1.1066 - <question id="resources-read" when="final">
1.1067 - Does your module read any resources from layers? For what purpose?
1.1068 -
1.1069 - <hint>
1.1070 - As this is some kind of intermodule dependency, it is a kind of API.
1.1071 - Please describe it and classify according to
1.1072 - <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
1.1073 - common stability categories</a>.
1.1074 - </hint>
1.1075 - </question>
1.1076 --->
1.1077 - <answer id="resources-read">
1.1078 - <p>
1.1079 - XXX no answer for resources-read
1.1080 - </p>
1.1081 - </answer>
1.1082 -
1.1083 -
1.1084 -
1.1085 -<!--
1.1086 - <question id="security-grant" when="final">
1.1087 - Does your code grant additional rights to some other code?
1.1088 - <hint>Avoid using a class loader that adds extra
1.1089 - permissions to loaded code unless really necessary.
1.1090 - Also note that your API implementation
1.1091 - can also expose unneeded permissions to enemy code by
1.1092 - calling AccessController.doPrivileged().</hint>
1.1093 - </question>
1.1094 --->
1.1095 - <answer id="security-grant">
1.1096 - <p>
1.1097 - XXX no answer for security-grant
1.1098 - </p>
1.1099 - </answer>
1.1100 -
1.1101 -
1.1102 -
1.1103 -<!--
1.1104 - <question id="security-policy" when="final">
1.1105 - Does your functionality require modifications to the standard policy file?
1.1106 - <hint>Your code might pass control to third-party code not
1.1107 - coming from trusted domains. This could be code downloaded over the
1.1108 - network or code coming from libraries that are not bundled
1.1109 - with NetBeans. Which permissions need to be granted to which domains?</hint>
1.1110 - </question>
1.1111 --->
1.1112 - <answer id="security-policy">
1.1113 - <p>
1.1114 - XXX no answer for security-policy
1.1115 - </p>
1.1116 - </answer>
1.1117 -
1.1118 -</api-answers>