This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

View | Details | Raw Unified | Return to bug 248126
Collapse All | Expand All

(-)a/api.intent/arch.xml (+1138 lines)
Line 0 Link Here
1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
3
  <!ENTITY api-questions SYSTEM "../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
4
]>
5
6
<api-answers
7
  question-version="1.29"
8
  author="yourname@netbeans.org"
9
>
10
11
  &api-questions;
12
13
    <!--
14
            <question id="arch-overall" when="init">
15
                Describe the overall architecture.
16
                <hint>
17
                What will be API for
18
                <a href="http://wiki.netbeans.org/API_Design#Separate_API_for_clients_from_support_API">
19
                    clients and what support API</a>?
20
                What parts will be pluggable?
21
                How will plug-ins be registered? Please use <code>&lt;api type="export"/&gt;</code>
22
                to describe your general APIs and specify their
23
                <a href="http://wiki.netbeans.org/API_Stability#Private">
24
                stability categories</a>.
25
                If possible please provide simple diagrams.
26
                </hint>
27
            </question>
28
    -->
29
    <answer id="arch-overall">
30
        <p>
31
            This module was originally created to provide a way to handle
32
            clicks on hyperlinks in the output window. Some more sophisticated
33
            objects for describing intended operations can be added into this
34
            module in the future.
35
        </p>
36
        <p>
37
            The URI-based actions are useful if the front-end and back-end of
38
            the application is separated, e.g. in network environment. The
39
            actions can be specified on back-end, but handled on front-end,
40
            without any unnecessary communication.
41
        </p>
42
43
        <api
44
            name="OpenUriAPI"
45
            group="java"
46
            type="export"
47
            category="official"
48
            url="@org-netbeans-api-intent@/org/netbeans/api/intent/uri/package-summary.html"
49
        >
50
            <p>
51
                API for invoking some intended operation, specified by
52
                a URI. For example, for displaying a web page in browser, or for
53
                opening a source file in editor.
54
            </p>
55
        </api>
56
        <api
57
            name="OpenUriSPI"
58
            group="java"
59
            type="export"
60
            category="official"
61
            url="@org-netbeans-api-intent@/org/netbeans/spi/intent/uri/package-summary.html"
62
        >
63
            <p>
64
                SPI for handlers that are able to invoke proper operation for
65
                some URI.
66
            </p>
67
        </api>
68
    </answer>
69
70
71
72
    <!--
73
            <question id="arch-quality" when="init">
74
                How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html">quality</a>
75
                of your code be tested and
76
                how are future regressions going to be prevented?
77
                <hint>
78
                What kind of testing do
79
                you want to use? How much functionality, in which areas,
80
                should be covered by the tests? How you find out that your
81
                project was successful?
82
                </hint>
83
            </question>
84
    -->
85
    <answer id="arch-quality">
86
        <p>
87
            The code is checked by unit tests.
88
        </p>
89
    </answer>
90
91
92
93
    <!--
94
            <question id="arch-time" when="init">
95
                What are the time estimates of the work?
96
                <hint>
97
                Please express your estimates of how long the design, implementation,
98
                stabilization are likely to last. How many people will be needed to
99
                implement this and what is the expected milestone by which the work should be
100
                ready?
101
                </hint>
102
            </question>
103
    -->
104
    <answer id="arch-time">
105
        <p>
106
            Done.
107
        </p>
108
    </answer>
109
110
111
112
    <!--
113
        <question id="arch-usecases" when="init">
114
            <hint>
115
                Content of this answer will be displayed as part of page at
116
                http://www.netbeans.org/download/dev/javadoc/usecases.html
117
                You can use tags &lt;usecase name="name&gt; regular html description &lt;/usecase&gt;
118
                and if you want to use an URL you can prefix if with @TOP@ to begin
119
                at the root of your javadoc
120
            </hint>
121
122
                Describe the main <a href="http://wiki.netbeans.org/API_Design#The_Importance_of_Being_Use_Case_Oriented">
123
                use cases</a> of the new API. Who will use it under
124
                what circumstances? What kind of code would typically need to be written
125
                to use the module?
126
            </question>
127
    -->
128
    <answer id="arch-usecases">
129
        <usecase id="openUri" name="Invoke proper operation for a URI">
130
            <pre>
131
    UriIntents.openURI(new URI("test://a/b/c/"));
132
            </pre>
133
        </usecase>
134
135
        <usecase id="handleUri" name="Handle some URI clicked (or somehow invoked) in the application.">
136
            <pre>
137
   &nbsp;&#64;ServiceProvider(service = OpenUriHandler.class, position = 800)
138
    public class TestOpenUriHandler implements OpenUriHandler {
139
140
        public boolean handle(URI uri) {
141
            if ("http".equals(uri.getScheme())) {
142
                // open default browser
143
                return true;
144
            } else {
145
                return false;
146
            }
147
        }
148
    }
149
            </pre>
150
        </usecase>
151
    </answer>
152
153
154
155
    <!--
156
            <question id="arch-what" when="init">
157
                What is this project good for?
158
                <hint>
159
                Please provide here a few lines describing the project,
160
                what problem it should solve, provide links to documentation,
161
                specifications, etc.
162
                </hint>
163
            </question>
164
    -->
165
    <answer id="arch-what">
166
        <p>
167
            This module provides a contract between API clients that can express
168
            some intention to invoke an operation (specified e.g. by a URI) and
169
            SPI providers that can handle the URI.
170
        </p>
171
        <p>
172
            This is useful in client-server environments, where the intention
173
            can be constructed on server-side, but handled on client-side. The
174
            objects that describe the intention should be easy to construct,
175
            transfer and interpret.
176
        </p>
177
    </answer>
178
179
180
181
    <!--
182
            <question id="arch-where" when="impl">
183
                Where one can find sources for your module?
184
                <hint>
185
                    Please provide link to the Hg web client at
186
                    http://hg.netbeans.org/
187
                    or just use tag defaultanswer generate='here'
188
                </hint>
189
            </question>
190
    -->
191
    <answer id="arch-where">
192
        <defaultanswer generate='here' />
193
    </answer>
194
195
196
197
    <!--
198
            <question id="compat-deprecation" when="init">
199
                How the introduction of your project influences functionality
200
                provided by previous version of the product?
201
                <hint>
202
                If you are planning to deprecate/remove/change any existing APIs,
203
                list them here accompanied with the reason explaining why you
204
                are doing so.
205
                </hint>
206
            </question>
207
    -->
208
    <answer id="compat-deprecation">
209
        <p>
210
            No deprecation needed.
211
        </p>
212
    </answer>
213
214
215
216
    <!--
217
            <question id="compat-i18n" when="impl">
218
                Is your module correctly internationalized?
219
                <hint>
220
                Correct internationalization means that it obeys instructions 
221
                at <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/i18n-branding.html">
222
                NetBeans I18N pages</a>.
223
                </hint>
224
            </question>
225
    -->
226
    <answer id="compat-i18n">
227
        <p>
228
            Yes.
229
        </p>
230
    </answer>
231
232
233
234
    <!--
235
            <question id="compat-standards" when="init">
236
                Does the module implement or define any standards? Is the
237
                implementation exact or does it deviate somehow?
238
            </question>
239
    -->
240
    <answer id="compat-standards">
241
        <p>
242
            No standards.
243
        </p>
244
    </answer>
245
246
247
248
<!--
249
        <question id="compat-version" when="impl">
250
            Can your module coexist with earlier and future
251
            versions of itself? Can you correctly read all old settings? Will future
252
            versions be able to read your current settings? Can you read
253
            or politely ignore settings stored by a future version?
254
255
                <hint>
256
                Very helpful for reading settings is to store version number
257
                there, so future versions can decide whether how to read/convert
258
                the settings and older versions can ignore the new ones.
259
                </hint>
260
            </question>
261
    -->
262
    <answer id="compat-version">
263
        <p>
264
            No settings are read or written.
265
        </p>
266
    </answer>
267
268
269
270
    <!--
271
            <question id="dep-jre" when="final">
272
                Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
273
                <hint>
274
                It is expected that if your module runs on 1.x that it will run
275
                on 1.x+1 if no, state that please. Also describe here cases where
276
                you run different code on different versions of JRE and why.
277
                </hint>
278
            </question>
279
    -->
280
    <answer id="dep-jre">
281
        <p>
282
            1.6
283
        </p>
284
    </answer>
285
286
287
288
    <!--
289
            <question id="dep-jrejdk" when="final">
290
                Do you require the JDK or is the JRE enough?
291
            </question>
292
    -->
293
    <answer id="dep-jrejdk">
294
        <p>
295
            JRE
296
        </p>
297
    </answer>
298
299
300
301
    <!--
302
            <question id="dep-nb" when="init">
303
                What other NetBeans projects and modules does this one depend on?
304
                <hint>
305
                Depending on other NetBeans projects influnces the ability of
306
                users of your work to customize their own branded version of
307
                NetBeans by enabling and disabling some modules. Too
308
                much dependencies restrict this kind of customization. If that
309
                is your case, then you may want to split your functionality into
310
                pieces of autoload, eager and regular modules which can be
311
                enabled independently. Usually the answer to this question
312
                is generated from your <code>project.xml</code> file, but
313
                if it is not guessed correctly, you can suppress it by
314
                specifying &lt;defaultanswer generate="none"/&gt; and
315
                write here your own. Please describe such projects as imported APIs using
316
                the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>.
317
                By doing this information gets listed in the summary page of your
318
                javadoc.
319
                </hint>
320
            </question>
321
    -->
322
    <answer id="dep-nb">
323
        <defaultanswer generate='here' />
324
    </answer>
325
326
327
328
    <!--
329
        <question id="dep-non-nb" when="init">
330
            What other projects outside NetBeans does this one depend on?
331
332
                <hint>
333
                Depending on 3rd party libraries is always problematic,
334
                especially if they are not open source, as that complicates
335
                the licensing scheme of NetBeans. Please enumerate your
336
                external dependencies here, so it is correctly understood since
337
                the begining what are the legal implications of your project.
338
                Also please note that
339
                some non-NetBeans projects are packaged as NetBeans modules
340
                (see <a href="http://libs.netbeans.org/">libraries</a>) and
341
                it is preferred to use this approach when more modules may
342
                depend and share such third-party libraries.
343
                </hint>
344
            </question>
345
    -->
346
    <answer id="dep-non-nb">
347
        <p>
348
            No non-NB dependencies.
349
        </p>
350
    </answer>
351
352
353
354
    <!--
355
            <question id="dep-platform" when="init">
356
                On which platforms does your module run? Does it run in the same
357
                way on each?
358
                <hint>
359
                If you plan any dependency on OS or any usage of native code,
360
                please describe why you are doing so and describe how you envision
361
                to enforce the portability of your code.
362
                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
363
                enabled modules</a> which together with autoload/eager modules
364
                can allow you to enable to provide the best OS aware support
365
                on certain OSes while providing compatibility bridge on the not
366
                supported ones.
367
                Also please list the supported
368
                OSes/HW platforms and mentioned the lovest version of JDK required
369
                for your project to run on. Also state whether JRE is enough or
370
                you really need JDK.
371
                </hint>
372
            </question>
373
    -->
374
    <answer id="dep-platform">
375
        <p>
376
            Any platform.
377
        </p>
378
    </answer>
379
380
381
382
    <!--
383
            <question id="deploy-dependencies" when="final">
384
                What do other modules need to do to declare a dependency on this one,
385
                in addition to or instead of the normal module dependency declaration
386
                (e.g. tokens to require)?
387
                <hint>
388
                    Provide a sample of the actual lines you would add to a module manifest
389
                    to declare a dependency, for example OpenIDE-Module-Requires: some.token.
390
                    If other modules should not depend on this module, or should just use a
391
                    simple regular module dependency, you can just answer "nothing". If you
392
                    intentionally expose a semistable API to clients using implementation
393
                    dependencies, you should mention that here (but there is no need to give
394
                    an example of usage).
395
                </hint>
396
            </question>
397
    -->
398
    <answer id="deploy-dependencies">
399
        <p>
400
            Standard module dependency is sufficient.
401
        </p>
402
    </answer>
403
404
405
406
    <!--
407
        <question id="deploy-jar" when="impl">
408
            Do you deploy just module JAR file(s) or other files as well?
409
            <hint>
410
            Usually a module consist of one JAR file (perhaps with Class-Path
411
            extensions) and also a configuration file that enables it. If you
412
            have any other files, use
413
            &lt;api group="java.io.File" name="yourname" type="export" category="friend"&gt;...&lt;/api&gt;
414
            to define the location, name and stability of your files (of course
415
            changing "yourname" and "friend" to suit your needs).
416
417
                If it uses more than one JAR, describe where they are located, how
418
                they refer to each other.
419
                If it consist of module JAR(s) and other files, please describe
420
                what is their purpose, why other files are necessary. Please
421
                make sure that installation/uninstallation leaves the system
422
                in state as it was before installation.
423
                </hint>
424
            </question>
425
    -->
426
    <answer id="deploy-jar">
427
        <p>
428
            Just module JAR.
429
        </p>
430
    </answer>
431
432
433
434
    <!--
435
            <question id="deploy-nbm" when="impl">
436
                Can you deploy an NBM via the Update Center?
437
                <hint>
438
                If not why?
439
                </hint>
440
            </question>
441
    -->
442
    <answer id="deploy-nbm">
443
        <p>
444
            Yes.
445
        </p>
446
    </answer>
447
448
449
450
<!--
451
        <question id="deploy-packages" when="init">
452
            Are packages of your module made inaccessible by not declaring them
453
            public?
454
455
                <hint>
456
                By default NetBeans build harness treats all packages are private.
457
                If you export some of them - either as public or friend packages,
458
                you should have a reason. If the reason is described elsewhere
459
                in this document, you can ignore this question.
460
                </hint>
461
            </question>
462
    -->
463
    <answer id="deploy-packages">
464
        <p>
465
            Only API and SPI packages are public.
466
        </p>
467
    </answer>
468
469
470
471
    <!--
472
            <question id="deploy-shared" when="final">
473
                Do you need to be installed in the shared location only, or in the user directory only,
474
                or can your module be installed anywhere?
475
                <hint>
476
                Installation location shall not matter, if it does explain why.
477
                Consider also whether <code>InstalledFileLocator</code> can help.
478
                </hint>
479
            </question>
480
    -->
481
    <answer id="deploy-shared">
482
        <p>
483
            Installation location does not matter.
484
        </p>
485
    </answer>
486
487
488
489
    <!--
490
        <question id="exec-ant-tasks" when="impl">
491
            Do you define or register any ant tasks that other can use?
492
493
                <hint>
494
                If you provide an ant task that users can use, you need to be very
495
                careful about its syntax and behaviour, as it most likely forms an
496
                      API for end users and as there is a lot of end users, their reaction
497
                when such API gets broken can be pretty strong.
498
                </hint>
499
            </question>
500
    -->
501
    <answer id="exec-ant-tasks">
502
        <p>
503
            No.
504
        </p>
505
    </answer>
506
507
508
509
    <!--
510
            <question id="exec-classloader" when="impl">
511
                Does your code create its own class loader(s)?
512
                <hint>
513
                A bit unusual. Please explain why and what for.
514
                </hint>
515
            </question>
516
    -->
517
    <answer id="exec-classloader">
518
        <p>
519
            No.
520
        </p>
521
    </answer>
522
523
524
525
    <!--
526
        <question id="exec-component" when="impl">
527
            Is execution of your code influenced by any (string) property
528
            of any of your components?
529
530
                <hint>
531
                Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
532
                or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
533
                a behavior of some code. This of course forms an interface that should
534
                be documented. Also if one depends on some interface that an object
535
                implements (<code>component instanceof Runnable</code>) that forms an
536
                API as well.
537
                </hint>
538
            </question>
539
    -->
540
    <answer id="exec-component">
541
        <p>
542
            No.
543
        </p>
544
    </answer>
545
546
547
548
    <!--
549
            <question id="exec-introspection" when="impl">
550
                Does your module use any kind of runtime type information (<code>instanceof</code>,
551
                work with <code>java.lang.Class</code>, etc.)?
552
                <hint>
553
                Check for cases when you have an object of type A and you also
554
                expect it to (possibly) be of type B and do some special action. That
555
                should be documented. The same applies on operations in meta-level
556
                (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
557
                </hint>
558
            </question>
559
    -->
560
    <answer id="exec-introspection">
561
        <p>
562
            No.
563
        </p>
564
    </answer>
565
566
567
568
    <!--
569
            <question id="exec-privateaccess" when="final">
570
                Are you aware of any other parts of the system calling some of
571
                your methods by reflection?
572
                <hint>
573
                If so, describe the "contract" as an API. Likely private or friend one, but
574
                still API and consider rewrite of it.
575
                </hint>
576
            </question>
577
    -->
578
    <answer id="exec-privateaccess">
579
        <p>
580
            No.
581
        </p>
582
    </answer>
583
584
585
586
    <!--
587
            <question id="exec-process" when="impl">
588
                Do you execute an external process from your module? How do you ensure
589
                that the result is the same on different platforms? Do you parse output?
590
                Do you depend on result code?
591
                <hint>
592
                If you feed an input, parse the output please declare that as an API.
593
                </hint>
594
            </question>
595
    -->
596
    <answer id="exec-process">
597
        <p>
598
            No.
599
        </p>
600
    </answer>
601
602
603
604
    <!--
605
            <question id="exec-property" when="impl">
606
                Is execution of your code influenced by any environment or
607
                Java system (<code>System.getProperty</code>) property?
608
                On a similar note, is there something interesting that you
609
                pass to <code>java.util.logging.Logger</code>? Or do you observe
610
                what others log?
611
                <hint>
612
                If there is a property that can change the behavior of your
613
                code, somebody will likely use it. You should describe what it does
614
                and the <a href="http://wiki.netbeans.org/API_Stability">stability category</a>
615
                of this API. You may use
616
                <pre>
617
                    &lt;api type="export" group="property" name="id" category="private" url="http://..."&gt;
618
                        description of the property, where it is used, what it influence, etc.
619
                    &lt;/api&gt;
620
                </pre>
621
                </hint>
622
            </question>
623
    -->
624
    <answer id="exec-property">
625
        <p>
626
            No.
627
        </p>
628
    </answer>
629
630
631
632
    <!--
633
            <question id="exec-reflection" when="impl">
634
                Does your code use Java Reflection to execute other code?
635
                <hint>
636
                This usually indicates a missing or insufficient API in the other
637
                part of the system. If the other side is not aware of your dependency
638
                this contract can be easily broken.
639
                </hint>
640
            </question>
641
    -->
642
    <answer id="exec-reflection">
643
        <p>
644
            No.
645
        </p>
646
    </answer>
647
648
649
650
    <!--
651
            <question id="exec-threading" when="init">
652
                What threading models, if any, does your module adhere to? How the
653
                project behaves with respect to threading?
654
                <hint>
655
                    Is your API threadsafe? Can it be accessed from any threads or
656
                    just from some dedicated ones? Any special relation to AWT and
657
                    its Event Dispatch thread? Also
658
                    if your module calls foreign APIs which have a specific threading model,
659
                    indicate how you comply with the requirements for multithreaded access
660
                    (synchronization, mutexes, etc.) applicable to those APIs.
661
                    If your module defines any APIs, or has complex internal structures
662
                    that might be used from multiple threads, declare how you protect
663
                    data against concurrent access, race conditions, deadlocks, etc.,
664
                    and whether such rules are enforced by runtime warnings, errors, assertions, etc.
665
                    Examples: a class might be non-thread-safe (like Java Collections); might
666
                    be fully thread-safe (internal locking); might require access through a mutex
667
                    (and may or may not automatically acquire that mutex on behalf of a client method);
668
                    might be able to run only in the event queue; etc.
669
                    Also describe when any events are fired: synchronously, asynchronously, etc.
670
                    Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations">Threading Recommendations</a> (in progress)
671
                </hint>
672
            </question>
673
    -->
674
    <answer id="exec-threading">
675
        <p>
676
            The API is threadsafe. SPI implementations should ensure proper
677
            synchronization.
678
        </p>
679
    </answer>
680
681
682
683
    <!--
684
        <question id="format-clipboard" when="impl">
685
            Which data flavors (if any) does your code read from or insert to
686
            the clipboard (by access to clipboard on means calling methods on <code>java.awt.datatransfer.Transferable</code>?
687
688
                <hint>
689
                Often Node's deal with clipboard by usage of <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
690
                Check your code for overriding these methods.
691
                </hint>
692
            </question>
693
    -->
694
    <answer id="format-clipboard">
695
        <p>
696
            No clipboard access.
697
        </p>
698
    </answer>
699
700
701
702
    <!--
703
            <question id="format-dnd" when="impl">
704
                Which protocols (if any) does your code understand during Drag &amp; Drop?
705
                <hint>
706
                Often Node's deal with clipboard by usage of <code>Node.drag, Node.getDropType</code>. 
707
                Check your code for overriding these methods. Btw. if they are not overridden, they
708
                by default delegate to <code>Node.clipboardCopy, Node.clipboardCut and Node.pasteTypes</code>.
709
                </hint>
710
            </question>
711
    -->
712
    <answer id="format-dnd">
713
        <p>
714
            No Drag &amp; Drop support.
715
        </p>
716
    </answer>
717
718
719
720
<!--
721
        <question id="format-types" when="impl">
722
            Which protocols and file formats (if any) does your module read or write on disk,
723
            or transmit or receive over the network? Do you generate an ant build script?
724
            Can it be edited and modified?
725
726
            <hint>
727
                <p>
728
                Files can be read and written by other programs, modules and users. If they influence
729
                your behaviour, make sure you either document the format or claim that it is a private
730
                api (using the &lt;api&gt; tag).
731
                </p>
732
                <p>
733
                If you generate an ant build file, this is very likely going to be seen by end users and
734
                they will be attempted to edit it. You should be ready for that and provide here a link
735
                to documentation that you have for such purposes and also describe how you are going to
736
                understand such files during next release, when you (very likely) slightly change the
737
                format.
738
                </p>
739
                </hint>
740
            </question>
741
    -->
742
    <answer id="format-types">
743
        <p>
744
            No files are read or written by this module.
745
        </p>
746
    </answer>
747
748
749
750
<!--
751
        <question id="lookup-lookup" when="init">
752
            Does your module use <code>org.openide.util.Lookup</code>
753
            or any similar technology to find any components to communicate with? Which ones?
754
755
                <hint>
756
                NetBeans is build around a generic registry of services called
757
                lookup. It is preferable to use it for registration and discovery
758
                if possible. See
759
                <a href="http://www.netbeans.org/download/dev/javadoc/org-openide-util/org/openide/util/lookup/doc-files/index.html">
760
                The Solution to Comunication Between Components
761
                </a>. If you do not plan to use lookup and insist usage
762
                of other solution, then please describe why it is not working for
763
                you.
764
                <br/>
765
                When filling the final version of your arch document, please
766
                describe the interfaces you are searching for, where
767
                are defined, whether you are searching for just one or more of them,
768
                if the order is important, etc. Also classify the stability of such
769
                API contract. Use &lt;api group=&amp;lookup&amp; /&gt; tag, so
770
                your information gets listed in the summary page of your javadoc.
771
                </hint>
772
            </question>
773
    -->
774
    <answer id="lookup-lookup">
775
        <p>
776
            The lookup is used to find registered <code>OpenUriHandler</code>s.
777
        </p>
778
    </answer>
779
780
781
782
    <!--
783
            <question id="lookup-register" when="final">
784
                Do you register anything into lookup for other code to find?
785
                <hint>
786
                Do you register using layer file or using a declarative annotation such as <code>@ServiceProvider</code>?
787
                Who is supposed to find your component?
788
                </hint>
789
            </question>
790
    -->
791
    <answer id="lookup-register">
792
        <p>
793
            No.
794
        </p>
795
    </answer>
796
797
798
799
    <!--
800
            <question id="lookup-remove" when="final">
801
                Do you remove entries of other modules from lookup?
802
                <hint>
803
                Why? Of course, that is possible, but it can be dangerous. Is the module
804
                your are masking resource from aware of what you are doing?
805
                </hint>
806
            </question>
807
    -->
808
    <answer id="lookup-remove">
809
        <p>
810
            No.
811
        </p>
812
    </answer>
813
814
815
816
    <!--
817
            <question id="perf-exit" when="final">
818
                Does your module run any code on exit?
819
            </question>
820
    -->
821
    <answer id="perf-exit">
822
        <p>
823
            No.
824
        </p>
825
    </answer>
826
827
828
829
    <!--
830
            <question id="perf-huge_dialogs" when="final">
831
                Does your module contain any dialogs or wizards with a large number of
832
                GUI controls such as combo boxes, lists, trees, or text areas?
833
            </question>
834
    -->
835
    <answer id="perf-huge_dialogs">
836
        <p>
837
            No.
838
        </p>
839
    </answer>
840
841
842
843
    <!--
844
            <question id="perf-limit" when="init">
845
                Are there any hard-coded or practical limits in the number or size of
846
                elements your code can handle?
847
                <hint>
848
                    Most of algorithms have increasing memory and speed complexity
849
                    with respect to size of data they operate on. What is the critical
850
                    part of your project that can be seen as a bottleneck with
851
                    respect to speed or required memory? What are the practical
852
                    sizes of data you tested your project with? What is your estimate
853
                    of potential size of data that would cause visible performance
854
                    problems? Is there some kind of check to detect such situation
855
                    and prevent "hard" crashes - for example the CloneableEditorSupport
856
                    checks for size of a file to be opened in editor
857
                    and if it is larger than 1Mb it shows a dialog giving the
858
                    user the right to decide - e.g. to cancel or commit suicide.
859
                </hint>
860
            </question>
861
    -->
862
    <answer id="perf-limit">
863
        <p>
864
            No.
865
        </p>
866
    </answer>
867
868
869
870
    <!--
871
            <question id="perf-mem" when="final">
872
                How much memory does your component consume? Estimate
873
                with a relation to the number of windows, etc.
874
            </question>
875
    -->
876
    <answer id="perf-mem">
877
        <p>
878
            Very little memory consumed.
879
        </p>
880
    </answer>
881
882
883
884
    <!--
885
            <question id="perf-menus" when="final">
886
                Does your module use dynamically updated context menus, or
887
                context-sensitive actions with complicated and slow enablement logic?
888
                <hint>
889
                    If you do a lot of tricks when adding actions to regular or context menus, you can significantly
890
                    slow down display of the menu, even when the user is not using your action. Pay attention to
891
                    actions you add to the main menu bar, and to context menus of foreign nodes or components. If
892
                    the action is conditionally enabled, or changes its display dynamically, you need to check the
893
                    impact on performance. In some cases it may be more appropriate to make a simple action that is
894
                    always enabled but does more detailed checks in a dialog if it is actually run.
895
                </hint>
896
            </question>
897
    -->
898
    <answer id="perf-menus">
899
        <p>
900
            No.
901
        </p>
902
    </answer>
903
904
905
906
    <!--
907
        <question id="perf-progress" when="final">
908
            Does your module execute any long-running tasks?
909
910
                <hint>Long running tasks should never block
911
                AWT thread as it badly hurts the UI
912
                <a href="http://performance.netbeans.org/responsiveness/issues.html">
913
                responsiveness</a>.
914
                Tasks like connecting over
915
                network, computing huge amount of data, compilation
916
                be done asynchronously (for example
917
                using <code>RequestProcessor</code>), definitively it should
918
                not block AWT thread.
919
                </hint>
920
            </question>
921
    -->
922
    <answer id="perf-progress">
923
        <p>
924
            No.
925
        </p>
926
    </answer>
927
928
929
930
    <!--
931
            <question id="perf-scale" when="init">
932
                Which external criteria influence the performance of your
933
                program (size of file in editor, number of files in menu,
934
                in source directory, etc.) and how well your code scales?
935
                <hint>
936
                Please include some estimates, there are other more detailed
937
                questions to answer in later phases of implementation.
938
                </hint>
939
            </question>
940
    -->
941
    <answer id="perf-scale">
942
        <p>
943
            Code in the module is very simple. Performance is incluenced mosly
944
            by SPI implementations, which should run quite quickly.
945
        </p>
946
    </answer>
947
948
949
950
    <!--
951
            <question id="perf-spi" when="init">
952
                How the performance of the plugged in code will be enforced?
953
                <hint>
954
                If you allow foreign code to be plugged into your own module, how
955
                do you enforce that it will behave correctly and quickly and will not
956
                negatively influence the performance of your own module?
957
                </hint>
958
            </question>
959
    -->
960
    <answer id="perf-spi">
961
        <p>
962
            This is mentioned in JavaDoc of SPI classes.
963
        </p>
964
    </answer>
965
966
967
968
    <!--
969
            <question id="perf-startup" when="final">
970
                Does your module run any code on startup?
971
            </question>
972
    -->
973
    <answer id="perf-startup">
974
        <p>
975
            No.
976
        </p>
977
    </answer>
978
979
980
981
    <!--
982
            <question id="perf-wakeup" when="final">
983
                Does any piece of your code wake up periodically and do something
984
                even when the system is otherwise idle (no user interaction)?
985
            </question>
986
    -->
987
    <answer id="perf-wakeup">
988
        <p>
989
            No.
990
        </p>
991
    </answer>
992
993
994
995
    <!--
996
        <question id="resources-file" when="final">
997
            Does your module use <code>java.io.File</code> directly?
998
999
                <hint>
1000
                NetBeans provide a logical wrapper over plain files called 
1001
                <code>org.openide.filesystems.FileObject</code> that
1002
                provides uniform access to such resources and is the preferred
1003
                way that should be used. But of course there can be situations when
1004
                this is not suitable.
1005
                </hint>
1006
            </question>
1007
    -->
1008
    <answer id="resources-file">
1009
        <p>
1010
            No.
1011
        </p>
1012
    </answer>
1013
1014
1015
1016
    <!--
1017
        <question id="resources-layer" when="final">
1018
            Does your module provide own layer? Does it create any files or
1019
            folders in it? What it is trying to communicate by that and with which
1020
            components?
1021
1022
                <hint>
1023
                NetBeans allows automatic and declarative installation of resources
1024
                by module layers. Module register files into appropriate places
1025
                and other components use that information to perform their task
1026
                (build menu, toolbar, window layout, list of templates, set of
1027
                options, etc.).
1028
                </hint>
1029
            </question>
1030
    -->
1031
    <answer id="resources-layer">
1032
        <p>
1033
            No.
1034
        </p>
1035
    </answer>
1036
1037
1038
1039
    <!--
1040
        <question id="resources-mask" when="final">
1041
            Does your module mask/hide/override any resources provided by other modules in
1042
            their layers?
1043
1044
                <hint>
1045
                If you mask a file provided by another module, you probably depend
1046
                on that and do not want the other module to (for example) change
1047
                the file's name. That module shall thus make that file available as an API
1048
                of some stability category.
1049
                </hint>
1050
            </question>
1051
    -->
1052
    <answer id="resources-mask">
1053
        <p>
1054
            No.
1055
        </p>
1056
    </answer>
1057
1058
1059
1060
    <!--
1061
            <question id="resources-preferences" when="final">
1062
                Does your module uses preferences via Preferences API? Does your module use NbPreferences or
1063
                or regular JDK Preferences ? Does it read, write or both ?
1064
                Does it share preferences with other modules ? If so, then why ?
1065
                <hint>
1066
                    You may use
1067
                        &lt;api type="export" group="preferences"
1068
                        name="preference node name" category="private"&gt;
1069
                        description of individual keys, where it is used, what it
1070
                        influences, whether the module reads/write it, etc.
1071
                        &lt;/api&gt;
1072
                    Due to XML ID restrictions, rather than /org/netbeans/modules/foo give the "name" as org.netbeans.modules.foo.
1073
                    Note that if you use NbPreferences this name will then be the same as the code name base of the module.
1074
                </hint>
1075
            </question>
1076
    -->
1077
    <answer id="resources-preferences">
1078
        <p>
1079
            No.
1080
        </p>
1081
    </answer>
1082
1083
1084
1085
    <!--
1086
        <question id="resources-read" when="final">
1087
            Does your module read any resources from layers? For what purpose?
1088
1089
                <hint>
1090
                As this is some kind of intermodule dependency, it is a kind of API.
1091
                Please describe it and classify according to
1092
                <a href="http://wiki.netbeans.org/API_Design#What_is_an_API.3F">
1093
                common stability categories</a>.
1094
                </hint>
1095
            </question>
1096
    -->
1097
    <answer id="resources-read">
1098
        <p>
1099
            No.
1100
        </p>
1101
    </answer>
1102
1103
1104
1105
    <!--
1106
            <question id="security-grant" when="final">
1107
                Does your code grant additional rights to some other code?
1108
                <hint>Avoid using a class loader that adds extra
1109
                permissions to loaded code unless really necessary.
1110
                Also note that your API implementation
1111
                can also expose unneeded permissions to enemy code by
1112
                calling AccessController.doPrivileged().</hint>
1113
            </question>
1114
    -->
1115
    <answer id="security-grant">
1116
        <p>
1117
            No.
1118
        </p>
1119
    </answer>
1120
1121
1122
1123
    <!--
1124
            <question id="security-policy" when="final">
1125
                Does your functionality require modifications to the standard policy file?
1126
                <hint>Your code might pass control to third-party code not
1127
                coming from trusted domains. This could be code downloaded over the
1128
                network or code coming from libraries that are not bundled
1129
                with NetBeans. Which permissions need to be granted to which domains?</hint>
1130
            </question>
1131
    -->
1132
    <answer id="security-policy">
1133
        <p>
1134
            No.
1135
        </p>
1136
    </answer>
1137
1138
</api-answers>
(-)a/api.intent/build.xml (+5 lines)
Line 0 Link Here
1
<?xml version="1.0" encoding="UTF-8"?>
2
<project basedir="." default="netbeans" name="api.intent">
3
    <description>Builds, tests, and runs the project org.netbeans.api.intent</description>
4
    <import file="../nbbuild/templates/projectized.xml"/>
5
</project>
(-)a/api.intent/manifest.mf (+6 lines)
Line 0 Link Here
1
Manifest-Version: 1.0
2
AutoUpdate-Show-In-Client: true
3
OpenIDE-Module: org.netbeans.api.intent
4
OpenIDE-Module-Localizing-Bundle: org/netbeans/api/intent/uri/Bundle.properties
5
OpenIDE-Module-Specification-Version: 1.0
6
(-)a/api.intent/nbproject/project.properties (+4 lines)
Line 0 Link Here
1
is.autoload=true
2
javac.source=1.6
3
javac.compilerargs=-Xlint -Xlint:-serial
4
javadoc.arch=${basedir}/arch.xml
(-)a/api.intent/nbproject/project.xml (+53 lines)
Line 0 Link Here
1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://www.netbeans.org/ns/project/1">
3
    <type>org.netbeans.modules.apisupport.project</type>
4
    <configuration>
5
        <data xmlns="http://www.netbeans.org/ns/nb-module-project/3">
6
            <code-name-base>org.netbeans.api.intent</code-name-base>
7
            <module-dependencies>
8
                <dependency>
9
                    <code-name-base>org.netbeans.api.annotations.common</code-name-base>
10
                    <build-prerequisite/>
11
                    <compile-dependency/>
12
                    <run-dependency>
13
                        <release-version>1</release-version>
14
                        <specification-version>1.25</specification-version>
15
                    </run-dependency>
16
                </dependency>
17
                <dependency>
18
                    <code-name-base>org.openide.util.base</code-name-base>
19
                    <build-prerequisite/>
20
                    <compile-dependency/>
21
                    <run-dependency>
22
                        <specification-version>9.1</specification-version>
23
                    </run-dependency>
24
                </dependency>
25
                <dependency>
26
                    <code-name-base>org.openide.util.lookup</code-name-base>
27
                    <build-prerequisite/>
28
                    <compile-dependency/>
29
                    <run-dependency>
30
                        <specification-version>8.26</specification-version>
31
                    </run-dependency>
32
                </dependency>
33
            </module-dependencies>
34
            <test-dependencies>
35
                <test-type>
36
                    <name>unit</name>
37
                    <test-dependency>
38
                        <code-name-base>org.netbeans.libs.junit4</code-name-base>
39
                        <compile-dependency/>
40
                    </test-dependency>
41
                    <test-dependency>
42
                        <code-name-base>org.netbeans.modules.nbjunit</code-name-base>
43
                        <compile-dependency/>
44
                    </test-dependency>
45
                </test-type>
46
            </test-dependencies>
47
            <public-packages>
48
                <package>org.netbeans.api.intent.uri</package>
49
                <package>org.netbeans.spi.intent.uri</package>
50
            </public-packages>
51
        </data>
52
    </configuration>
53
</project>
(-)a/api.intent/src/org/netbeans/api/intent/uri/Bundle.properties (+7 lines)
Line 0 Link Here
1
OpenIDE-Module-Display-Category=Infrastructure
2
OpenIDE-Module-Long-Description=\
3
    API for invoking intended operations (described by suitable type of object, e.g. \
4
    URI) by some of registered handlers.\n\
5
    SPI for handlers of possible intended operations.
6
OpenIDE-Module-Name=Intent API
7
OpenIDE-Module-Short-Description=Performing intended operations by suitable handlers
(-)a/api.intent/src/org/netbeans/api/intent/uri/UriIntents.java (+84 lines)
Line 0 Link Here
1
/*
2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3
 *
4
 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.
5
 *
6
 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7
 * Other names may be trademarks of their respective owners.
8
 *
9
 * The contents of this file are subject to the terms of either the GNU
10
 * General Public License Version 2 only ("GPL") or the Common
11
 * Development and Distribution License("CDDL") (collectively, the
12
 * "License"). You may not use this file except in compliance with the
13
 * License. You can obtain a copy of the License at
14
 * http://www.netbeans.org/cddl-gplv2.html
15
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16
 * specific language governing permissions and limitations under the
17
 * License.  When distributing the software, include this License Header
18
 * Notice in each file and include the License file at
19
 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
20
 * particular file as subject to the "Classpath" exception as provided
21
 * by Oracle in the GPL Version 2 section of the License file that
22
 * accompanied this code. If applicable, add the following below the
23
 * License Header, with the fields enclosed by brackets [] replaced by
24
 * your own identifying information:
25
 * "Portions Copyrighted [year] [name of copyright owner]"
26
 *
27
 * If you wish your version of this file to be governed by only the CDDL
28
 * or only the GPL Version 2, indicate your decision by adding
29
 * "[Contributor] elects to include this software in this distribution
30
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
31
 * single choice of license, a recipient has the option to distribute
32
 * your version of this file under either the CDDL, the GPL Version 2 or
33
 * to extend the choice of license to its licensees as provided above.
34
 * However, if you add GPL Version 2 code and therefore, elected the GPL
35
 * Version 2 license, then the option applies only if the new code is
36
 * made subject to such option by the copyright holder.
37
 *
38
 * Contributor(s):
39
 *
40
 * Portions Copyrighted 2014 Sun Microsystems, Inc.
41
 */
42
package org.netbeans.api.intent.uri;
43
44
import java.net.URI;
45
import java.util.Collection;
46
import org.netbeans.api.annotations.common.NonNull;
47
import org.netbeans.spi.intent.uri.OpenUriHandler;
48
import org.openide.util.Lookup;
49
import org.openide.util.Parameters;
50
51
/**
52
 * Utility class for dealing with URI-based intents.
53
 *
54
 * @author jhavlin
55
 */
56
public final class UriIntents {
57
58
    private UriIntents() {
59
    }
60
61
    /**
62
     * Choose appropriate handler for a URI that was clicked in the application
63
     * and perform it.
64
     *
65
     * @param uri URI describing the intended operation.
66
     *
67
     * @return True if some of registered handlers managed to handle the URI,
68
     * false if the URI cannot be handled.
69
     *
70
     * @see OpenUriHandler
71
     */
72
    public static boolean openURI(@NonNull URI uri) {
73
        Parameters.notNull("uri", uri);                                 //NOI18N
74
        Collection<? extends OpenUriHandler> handlers
75
                = Lookup.getDefault().lookupAll(OpenUriHandler.class);
76
77
        for (OpenUriHandler handler : handlers) {
78
            if (handler.handle(uri)) {
79
                return true;
80
            }
81
        }
82
        return false;
83
    }
84
}
(-)a/api.intent/src/org/netbeans/spi/intent/uri/OpenUriHandler.java (+83 lines)
Line 0 Link Here
1
/*
2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3
 *
4
 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.
5
 *
6
 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7
 * Other names may be trademarks of their respective owners.
8
 *
9
 * The contents of this file are subject to the terms of either the GNU
10
 * General Public License Version 2 only ("GPL") or the Common
11
 * Development and Distribution License("CDDL") (collectively, the
12
 * "License"). You may not use this file except in compliance with the
13
 * License. You can obtain a copy of the License at
14
 * http://www.netbeans.org/cddl-gplv2.html
15
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16
 * specific language governing permissions and limitations under the
17
 * License.  When distributing the software, include this License Header
18
 * Notice in each file and include the License file at
19
 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
20
 * particular file as subject to the "Classpath" exception as provided
21
 * by Oracle in the GPL Version 2 section of the License file that
22
 * accompanied this code. If applicable, add the following below the
23
 * License Header, with the fields enclosed by brackets [] replaced by
24
 * your own identifying information:
25
 * "Portions Copyrighted [year] [name of copyright owner]"
26
 *
27
 * If you wish your version of this file to be governed by only the CDDL
28
 * or only the GPL Version 2, indicate your decision by adding
29
 * "[Contributor] elects to include this software in this distribution
30
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
31
 * single choice of license, a recipient has the option to distribute
32
 * your version of this file under either the CDDL, the GPL Version 2 or
33
 * to extend the choice of license to its licensees as provided above.
34
 * However, if you add GPL Version 2 code and therefore, elected the GPL
35
 * Version 2 license, then the option applies only if the new code is
36
 * made subject to such option by the copyright holder.
37
 *
38
 * Contributor(s):
39
 *
40
 * Portions Copyrighted 2014 Sun Microsystems, Inc.
41
 */
42
package org.netbeans.spi.intent.uri;
43
44
import java.net.URI;
45
import org.netbeans.api.annotations.common.NonNull;
46
import org.netbeans.api.intent.uri.UriIntents;
47
import org.openide.util.lookup.ServiceProvider;
48
49
/**
50
 * SPI for handlers that can process URI hyperlinks that were clicked in the
51
 * application.
52
 *
53
 * If the front-end and back-end of the application is separated, clicked URI
54
 * hyperlinks can be handled on the front-end, possibly without any
55
 * communication with the back-end.
56
 *
57
 * @author jhavlin
58
 */
59
public interface OpenUriHandler {
60
61
    /**
62
     * Handle the passed URI, if it is supported by this handler.
63
     *
64
     * <p>
65
     * To register a handler, use {@link ServiceProvider} annotation. Ensure
66
     * that {@link ServiceProvider#position()} is set properly.
67
     * </p>
68
     * <p>
69
     * The code should run very quickly. Do not invoke any long-running tasks in
70
     * the handler. If the URI is accepted, consider performing the actual
71
     * operation in background.
72
     * </p>
73
     *
74
     * @param uri The URI to handle.
75
     *
76
     * @return True if the URI has been handled succesfully, false if this
77
     * handler doesn't support it and thus it should be passed to next available
78
     * handler.
79
     *
80
     * @see UriIntents#openURI(java.net.URI)
81
     */
82
    boolean handle(@NonNull URI uri);
83
}
(-)a/api.intent/test/unit/src/org/netbeans/api/intent/uri/UriIntentsTest.java (+93 lines)
Line 0 Link Here
1
/*
2
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3
 *
4
 * Copyright 2014 Oracle and/or its affiliates. All rights reserved.
5
 *
6
 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.
7
 * Other names may be trademarks of their respective owners.
8
 *
9
 * The contents of this file are subject to the terms of either the GNU
10
 * General Public License Version 2 only ("GPL") or the Common
11
 * Development and Distribution License("CDDL") (collectively, the
12
 * "License"). You may not use this file except in compliance with the
13
 * License. You can obtain a copy of the License at
14
 * http://www.netbeans.org/cddl-gplv2.html
15
 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
16
 * specific language governing permissions and limitations under the
17
 * License.  When distributing the software, include this License Header
18
 * Notice in each file and include the License file at
19
 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this
20
 * particular file as subject to the "Classpath" exception as provided
21
 * by Oracle in the GPL Version 2 section of the License file that
22
 * accompanied this code. If applicable, add the following below the
23
 * License Header, with the fields enclosed by brackets [] replaced by
24
 * your own identifying information:
25
 * "Portions Copyrighted [year] [name of copyright owner]"
26
 *
27
 * If you wish your version of this file to be governed by only the CDDL
28
 * or only the GPL Version 2, indicate your decision by adding
29
 * "[Contributor] elects to include this software in this distribution
30
 * under the [CDDL or GPL Version 2] license." If you do not indicate a
31
 * single choice of license, a recipient has the option to distribute
32
 * your version of this file under either the CDDL, the GPL Version 2 or
33
 * to extend the choice of license to its licensees as provided above.
34
 * However, if you add GPL Version 2 code and therefore, elected the GPL
35
 * Version 2 license, then the option applies only if the new code is
36
 * made subject to such option by the copyright holder.
37
 *
38
 * Contributor(s):
39
 *
40
 * Portions Copyrighted 2014 Sun Microsystems, Inc.
41
 */
42
package org.netbeans.api.intent.uri;
43
44
import java.net.URI;
45
import java.net.URISyntaxException;
46
import org.junit.Test;
47
import static org.junit.Assert.*;
48
import org.netbeans.junit.MockServices;
49
import org.netbeans.spi.intent.uri.OpenUriHandler;
50
51
/**
52
 *
53
 * @author jhavlin
54
 */
55
public class UriIntentsTest {
56
57
    @Test
58
    public void testOpenUri() throws URISyntaxException {
59
60
        boolean res1 = UriIntents.openURI(new URI("test://a/b/c/"));
61
        assertFalse(res1);
62
63
        MockServices.setServices(TestOpenUriHandler.class);
64
        try {
65
            assertFalse(TestOpenUriHandler.HANDLED);
66
            boolean res2 = UriIntents.openURI(new URI("test://a/b/c/"));
67
            assertTrue(res2);
68
            assertTrue(TestOpenUriHandler.HANDLED);
69
70
            boolean res3 = UriIntents.openURI(new URI("other://x/y/z/"));
71
            assertFalse(res3);
72
        } finally {
73
            MockServices.setServices();
74
        }
75
    }
76
77
    @SuppressWarnings("PublicInnerClass")
78
    public static class TestOpenUriHandler implements OpenUriHandler {
79
80
        @SuppressWarnings("PackageVisibleField")
81
        static boolean HANDLED = false;
82
83
        @Override
84
        public boolean handle(URI uri) {
85
            if ("test".equals(uri.getScheme())) {
86
                HANDLED = true;
87
                return true;
88
            } else {
89
                return false;
90
            }
91
        }
92
    }
93
}

Return to bug 248126