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