-
Notifications
You must be signed in to change notification settings - Fork 27
Expand file tree
/
Copy pathorb_notes.html
More file actions
2089 lines (1910 loc) · 113 KB
/
Copy pathorb_notes.html
File metadata and controls
2089 lines (1910 loc) · 113 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<!--
Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the
terms of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
v. 1.0 which is available at
http://www.eclipse.org/org/documents/edl-v10.php.
This Source Code may also be made available under the following Secondary
Licenses when the conditions for such availability set forth in the Eclipse
Public License v. 2.0 are satisfied: GNU General Public License v2.0
w/Classpath exception which is available at
https://www.gnu.org/software/classpath/license.html.
SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause OR GPL-2.0 WITH
Classpath-exception-2.0
-->
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<META name="GENERATOR" content="hevea 1.08">
<STYLE type="text/css">
.toc{list-style:none;}
.title{margin:auto;text-align:center}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
DIV TABLE{margin-left:inherit;margin-right:inherit;}
PRE{text-align:left;margin-left:0ex;margin-right:auto;}
BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
.part{margin:auto;text-align:center}
</STYLE>
</HEAD>
<BODY >
<!--HEVEA command line is: /usr/bin/hevea -s /tmp/lyx_tmpdir8354fpSyDz/lyx_tmpbuf0/orb_notes.tex -->
<!--HTMLHEAD-->
<!--ENDHTML-->
<!--PREFIX <ARG ></ARG>-->
<!--CUT DEF chapter 1 -->
<BR>
<TABLE CLASS="title">
<TR><TD></TD>
</TR></TABLE><BLOCKQUOTE CLASS="quote"><B>Abstract: </B>
Comprehensive documentation on the Sun Java ORB.<!--TOC chapter Contents-->
<H1 CLASS="chapter">Contents</H1><!--SEC END -->
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc1">Chapter 1 Starting Points</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc2">1.1 Changes for the GlassFish-CORBA project</A>
<LI CLASS="li-toc"><A HREF="#htoc3">1.2 ORB Development procedures</A>
<LI CLASS="li-toc"><A HREF="#htoc4">1.3 Workspace Structure and Builds</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc5">1.3.1 docs</A>
<LI CLASS="li-toc"><A HREF="#htoc6">1.3.2 ORB source</A>
<LI CLASS="li-toc"><A HREF="#htoc7">1.3.3 ORB Renaming</A>
<LI CLASS="li-toc"><A HREF="#htoc8">1.3.4 ORB Build Files</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc9">1.3.4.1 Building the ORB</A>
<LI CLASS="li-toc"><A HREF="#htoc10">1.3.4.2 Structure of the build files</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc11">1.3.5 tests</A>
<LI CLASS="li-toc"><A HREF="#htoc12">1.3.6 libraries</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc13">1.4 ORB Developer Tests</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc14">1.4.1 Test Suites</A>
<LI CLASS="li-toc"><A HREF="#htoc15">1.4.2 debugging tests</A>
<LI CLASS="li-toc"><A HREF="#htoc16">1.4.3 Debugging and Running a single test</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc17">1.5 ORB SQE Tests</A>
<LI CLASS="li-toc"><A HREF="#htoc18">1.6 Thoughts on Middleware goals</A>
<LI CLASS="li-toc"><A HREF="#htoc19">1.7 ORB Coding Practices</A>
<LI CLASS="li-toc"><A HREF="#htoc20">1.8 Supporting JDK and App Server</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc21">Chapter 2 The ORB Class</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc22">2.1 Inheritance Structure</A>
<LI CLASS="li-toc"><A HREF="#htoc23">2.2 ORB SPI structure </A>
<LI CLASS="li-toc"><A HREF="#htoc24">2.3 ORB Initialization</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc25">2.3.1 The Configuration Framework</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc26">2.3.1.1 DataCollector</A>
<LI CLASS="li-toc"><A HREF="#htoc27">2.3.1.2 Operation</A>
<LI CLASS="li-toc"><A HREF="#htoc28">2.3.1.3 PropertyParser</A>
<LI CLASS="li-toc"><A HREF="#htoc29">2.3.1.4 Base Classes for Parsing Properties</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc30">2.3.2 Details of ORB.init</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc31">2.3.2.1 The ORB configurator</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc32">2.3.3 Initializing the ORB in the App Server</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc33">2.4 ORB Shutdown</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc34">Chapter 3 Dispatch Path Overview</A>
<LI CLASS="li-toc"><A HREF="#htoc35">Chapter 4 Presentation</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc36">4.1 Stubs and Skeletons</A>
<LI CLASS="li-toc"><A HREF="#htoc37">4.2 Data types</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc38">Chapter 5 Encoding</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc39">5.1 Repository IDs</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc40">Chapter 6 Protocol</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc41">6.1 Subcontract IDs</A>
<LI CLASS="li-toc"><A HREF="#htoc42">6.2 IORs</A>
<LI CLASS="li-toc"><A HREF="#htoc43">6.3 Service Contexts</A>
<LI CLASS="li-toc"><A HREF="#htoc44">6.4 GIOP Message Representation</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc45">Chapter 7 Transport</A>
<LI CLASS="li-toc"><A HREF="#htoc46">Chapter 8 Other Aspects of the ORB</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc47">8.1 Object Adapters</A>
<LI CLASS="li-toc"><A HREF="#htoc48">8.2 The RequestDispatcherRegistry</A>
<LI CLASS="li-toc"><A HREF="#htoc49">8.3 Encoding Details</A>
<LI CLASS="li-toc"><A HREF="#htoc50">8.4 ORB Logging</A>
<LI CLASS="li-toc"><A HREF="#htoc51">8.5 ORB Monitoring</A>
<LI CLASS="li-toc"><A HREF="#htoc52">8.6 ORB versioning</A>
<LI CLASS="li-toc"><A HREF="#htoc53">8.7 ORBD and Server Activation</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc54">8.7.1 current model</A>
<LI CLASS="li-toc"><A HREF="#htoc55">8.7.2 ideas for using ORT</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc56">8.8 Portable Interceptors</A>
<LI CLASS="li-toc"><A HREF="#htoc57">8.9 RMI-IIOP Implementation</A>
<LI CLASS="li-toc"><A HREF="#htoc58">8.10 Resolvers</A>
<LI CLASS="li-toc"><A HREF="#htoc59">8.11 Name Services</A>
<LI CLASS="li-toc"><A HREF="#htoc60">8.12 ORB and App Server Integration</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc61">Chapter 9 Utilities</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc62">9.1 Fast Object Copying</A>
<LI CLASS="li-toc"><A HREF="#htoc63">9.2 Dynamic Code Generation</A>
<LI CLASS="li-toc"><A HREF="#htoc64">9.3 Useful utilities</A>
<LI CLASS="li-toc"><A HREF="#htoc65">9.4 FSM Framework</A>
<LI CLASS="li-toc"><A HREF="#htoc66">9.5 Graph Utilities</A>
<LI CLASS="li-toc"><A HREF="#htoc67">9.6 JDK 5 Specific Utilities</A>
<LI CLASS="li-toc"><A HREF="#htoc68">9.7 Timing Framework</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc69">Chapter 10 Living with our legacy</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc70">10.1 Testing Principles</A>
<LI CLASS="li-toc"><A HREF="#htoc71">10.2 Benchmarking</A>
<LI CLASS="li-toc"><A HREF="#htoc72">10.3 FOLB Support</A>
<LI CLASS="li-toc"><A HREF="#htoc73">10.4 HWLB Support</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc74">Chapter 11 Compilers</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc75">11.1 New rmic iiop backend</A>
<LI CLASS="li-toc"><A HREF="#htoc76">11.2 idlj</A>
</UL>
<LI CLASS="li-toc"><A HREF="#htoc77">Chapter 12 Future Directions</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc78">12.1 Embedded Languages</A>
<LI CLASS="li-toc"><A HREF="#htoc79">12.2 Components</A>
<LI CLASS="li-toc"><A HREF="#htoc80">12.3 Fast Marshalling</A>
<LI CLASS="li-toc"><A HREF="#htoc81">12.4 Security</A>
<LI CLASS="li-toc"><A HREF="#htoc82">12.5 Better handling of Invocation Info</A>
</UL>
</UL>
</BLOCKQUOTE>
<!--TOC chapter Starting Points-->
<H1 CLASS="chapter"><A NAME="htoc1">Chapter 1</A> Starting Points</H1><!--SEC END -->
<!--TOC section Changes for the GlassFish-CORBA project-->
<H2 CLASS="section"><A NAME="htoc2">1.1</A> Changes for the GlassFish-CORBA project</H2><!--SEC END -->
This document originally described CORAB development internally in
Sun's TeamWare environment. We have since switched to using Mercurial,
both internally and externally. The glassfish-corba project still
uses CVS, but only to maintain easy access to the documents.<BR>
<BR>
Some of the policies and procedures described here will be changed
as we continue moving all of our work to the open internet glassfish-corba
project.<BR>
<BR>
<!--TOC section ORB Development procedures-->
<H2 CLASS="section"><A NAME="htoc3">1.2</A> ORB Development procedures</H2><!--SEC END -->
Over the years, we have established a fairly successful development
methodology for working on the ORB. Any piece of work from a minor
bugfix to a major new subsystem iterates over the same stages one
or more times. I'll discuss this briefly here, but the details will
appear below.
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Discuss or document the design. This can take many forms, ranging
from an informal discussion to a written document. Written documents
have in the past been done in many different formats, including email,
text files, FrameMaker documents, StarOffice documents, HTML, XML
and DocBook, and L<sup>A</sup>T<sub>E</sub>X (about the only thing none of us have used
seems to be Word!). Going forward, all of these are still viable in
different ways, but I'd really like to make sure that we capture all
of the design efforts into our documentation collection. All current
documentation is found in the CORBA workspace in the www directory,
and all future documentation should either be there, or in the actual
source code.
<LI CLASS="li-enumerate">Develop the code. This include writing both the code to implement
the change and the code to test it. Bugs need a test that fails before
the change is made, and that passes after the change. All tests must
be incorporated somewhere in the CORBA test suites (see sub:Test-Suites)
so that they can be run automatically. Test execution speed is important,
so make the test as fast as possible. Please follow the principles
discussed in sec:Thoughts-on-Middleware and in sec:ORB-Coding-Practices.
<LI CLASS="li-enumerate">Verify that nothing has been broken by the change. This requires running
all of the CORBA test suites, and fixing any problems that show up
(see sub:debugging-tests for help on debugging tests).
<LI CLASS="li-enumerate">Prepare a webrev for a code review. The webrev tool is available on
SWAN (Sun's internal network) in /java/devtools/share/bin. Read the
comments in this kshell script for details. (TBD: where is webrev
outside of Sun?). Webrevs have the advantage that they can be archived
standalone, and this is probably a good thing to do. Another viable
option is to use a tool like meld (see meld <A HREF="http://meld.sourceforge.net/">)</A>
that can do directory diffs.
<LI CLASS="li-enumerate">Have at least 1 (and preferably more) developer from the GlassFish-CORBA
team review the changes. Make any necessary corrections from the review,
and re-review if necessary.<BR>
<BR>
TBD: Currently we conduct all code reviews in real time, usually via
phone conference (since this has been a distributed team for a long
time). We need to investigate this in the open source world, and find
a more scalable method that works asynchronously. Something like Google's
Mondrian would be a good choice, if it were available.</OL>
<!--TOC section Workspace Structure and Builds-->
<H2 CLASS="section"><A NAME="htoc4">1.3</A> Workspace Structure and Builds<A NAME="sec:Workspace-Structure-and"></A></H2><!--SEC END -->
The workspace is divided into a number of directories. The current
structure will change somewhat after I finish work on another putback
that restructures the workspace to simplify its organization and remove
obsolete junk.<BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">Directory</DIV></TD>
<TD VALIGN=top ALIGN=left>Purpose</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">build</DIV></TD>
<TD VALIGN=top ALIGN=left>created during build process</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">build/classes</DIV></TD>
<TD VALIGN=top ALIGN=left>compiled classes</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">build/gensrc</DIV></TD>
<TD VALIGN=top ALIGN=left>Java source code generated by build</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">build/lib</DIV></TD>
<TD VALIGN=top ALIGN=left>miscellaneous idl files for the interface repository</TD>
</TR>
<TR><TD ALIGN=left NOWRAP>build/release/lib</TD>
<TD VALIGN=top ALIGN=left>Jar files that are the build results:
<UL CLASS="itemize"><LI CLASS="li-itemize">
idlj.jar: the IDL compiler
<LI CLASS="li-itemize">omgapi.jar: the OMG API classes that are NOT part of JDK 5 or 6
<LI CLASS="li-itemize">orblib.jar: the ORB library files from the orblib directory
<LI CLASS="li-itemize">peorb.jar: the main ORB files
</UL></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">build/rename/ee</DIV></TD>
<TD VALIGN=top ALIGN=left>Where the ant rename target puts a copy of the workspace</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">lib</DIV></TD>
<TD VALIGN=top ALIGN=left>various jar files needed to build and test the ORB:
<UL CLASS="itemize"><LI CLASS="li-itemize">
emma (for code coverage)
<LI CLASS="li-itemize">ejb 2.1 APIs (for a codegen test)
<LI CLASS="li-itemize">japex (to compile against for StandardTest)
<LI CLASS="li-itemize">jscheme (used for generating log wrappers)
<LI CLASS="li-itemize">junit and testng (for testing)
</UL></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">make</DIV></TD>
<TD VALIGN=top ALIGN=left>contains ant build files</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">nbproject</DIV></TD>
<TD VALIGN=top ALIGN=left>contains NetBeans support to treat workspace as a NetBeans project</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">orblib</DIV></TD>
<TD VALIGN=top ALIGN=left>Standalone ORB library source files (delivered to orblib.jar)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">src</DIV></TD>
<TD VALIGN=top ALIGN=left>main ORB source code (delivered to peorb.jar)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">test</DIV></TD>
<TD VALIGN=top ALIGN=left>ORB test source (and orblibrary as well at present)</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="flushleft">tools</DIV></TD>
<TD VALIGN=top ALIGN=left>IOR parser</TD>
</TR></TABLE><BR>
<!--TOC subsection docs-->
<H3 CLASS="subsection"><A NAME="htoc5">1.3.1</A> docs<A NAME="sub:docs"></A></H3><!--SEC END -->
There are quite a few files here. This will eventually include all
of the useful files from /java/j2ee/CORBA. Most of the doc files in
the current workspace are useless, with one important exception: the
eea1 directory. These are Everett Anderson's notes on the design and
implementation of the GIOP layer, and are still quite useful. This
also documents the RMI-IIOP stream format version 2 implementation.<BR>
<BR>
<!--TOC subsection ORB source-->
<H3 CLASS="subsection"><A NAME="htoc6">1.3.2</A> ORB source<A NAME="sub:ORB-source"></A></H3><!--SEC END -->
Generally, most ORB implementation source packages have two parts:
an interface defined in an spi package, and an implementation in an
impl package. We will generally discuss these together.<BR>
<BR>
The ORB source code is divided into several parts:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>src/solaris</B><DD CLASS="dd-description">Useless and should be removed.
<DT CLASS="dt-description"><B>src/share/classes</B><DD CLASS="dd-description">This contains the main part of the source code.
It can be further divided into:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>org</B><DD CLASS="dd-description">OMG standard CORBA APIs
<DT CLASS="dt-description"><B>javax</B><DD CLASS="dd-description">OMG standard RMI-IIOP APIs
<DT CLASS="dt-description"><B>sun/rmi</B><DD CLASS="dd-description">rmic compiler
<DT CLASS="dt-description"><B>sun/corba</B><DD CLASS="dd-description">CORBA Bridge class, which isolates ORB dependencies on
non-public JDK APIs
<DT CLASS="dt-description"><B>com/sun/corba/ee</B><DD CLASS="dd-description">Main body of ORB source code (automatically renamed
to ee package for app server build)
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>GiopIDL</B><DD CLASS="dd-description">IDL files for GIOP protocol definitions
<DT CLASS="dt-description"><B>PortableActivationIDL</B><DD CLASS="dd-description">Old ideas for ORBD rewrite; to be removed
<DT CLASS="dt-description"><B>experimental/portableactivation</B><DD CLASS="dd-description">Part of ORBD rewrite; to be removed
<DT CLASS="dt-description"><B>impl/spi</B><DD CLASS="dd-description">The main part of the ORB implementation
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>activation</B><DD CLASS="dd-description">ORBD
<DT CLASS="dt-description"><B>copyobject</B><DD CLASS="dd-description">Object copier code with special hooks for CORBA
<DT CLASS="dt-description"><B>corba(impl)</B><DD CLASS="dd-description">Implementation of OMG CORBA APIs (but not org.omg.CORBA.ORB)
<DT CLASS="dt-description"><B>dynamicany</B><DD CLASS="dd-description">Dynamic Any support
<DT CLASS="dt-description"><B>encoding</B><DD CLASS="dd-description">Input and output streams for CDR and JSG (Java Serialization
for GIOP). PEPt encoding level code.
<DT CLASS="dt-description"><B>extension(spi)</B><DD CLASS="dd-description">Some AS-specific CORBA policies used by EJB for creating
POAs.
<DT CLASS="dt-description"><B>folb</B><DD CLASS="dd-description">Code for support IIOP failover and load balancing in GlassFish
v2
<DT CLASS="dt-description"><B>interceptors(impl)</B><DD CLASS="dd-description">Portable Interceptor implementation
<DT CLASS="dt-description"><B>io(impl)</B><DD CLASS="dd-description">Code to analyze classes and implement streams for GIOP.
This is the valuehandler implementation, which can be used by other
ORBs.
<DT CLASS="dt-description"><B>ior</B><DD CLASS="dd-description">How we represent IORs
<DT CLASS="dt-description"><B>javax(impl)</B><DD CLASS="dd-description">RMI-IIOP implementation
<DT CLASS="dt-description"><B>legacy</B><DD CLASS="dd-description">Some AS-specific extensions to interceptors and some connection
management support
<DT CLASS="dt-description"><B>logging</B><DD CLASS="dd-description">Logging infrastructure used by generated log wrappers
<DT CLASS="dt-description"><B>monitoring</B><DD CLASS="dd-description">ORB monitoring framework
<DT CLASS="dt-description"><B>naming</B><DD CLASS="dd-description">CosNaming service implementations
<DT CLASS="dt-description"><B>oa</B><DD CLASS="dd-description">Object Adapters. This includes:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>poa(impl)</B><DD CLASS="dd-description">The Portable Object Adapter implementation
<DT CLASS="dt-description"><B>toa(impl)</B><DD CLASS="dd-description">Simple OA used for orb.connect/disconnect (JDK 1.2) and
old RMI-IIOP support
<DT CLASS="dt-description"><B>rfm</B><DD CLASS="dd-description">The ReferenceFactoryManager, used to enable suspend/resume of
ORB processing for dynamic reconfiguration. Used to support dynamic
FOLB in AS9.
<DT CLASS="dt-description"><B>*.java</B><DD CLASS="dd-description">The OA SPI.
</DL>
<DT CLASS="dt-description"><B>orb</B><DD CLASS="dd-description">The implementation of the ORB class, and associated configuration
framework. The configuration code should really be moved into a utility
library.
<DT CLASS="dt-description"><B>orbutil</B><DD CLASS="dd-description">(impl) Utilities not related to RMI-IIOP. This includes
JDK 1.3.1 backwards compatibility support, the threadpool, and a few
other miscellaneous utilities, and ORBConstants. ORBConstants is very
commonly used in the ORB and App server and should be moved to an
SPI package.
<DT CLASS="dt-description"><B>presentation</B><DD CLASS="dd-description">PEPt presentation level code for dynamic RMI-IIOP
<DT CLASS="dt-description"><B>plugin(impl only)</B><DD CLASS="dd-description">ORB Hardware loadbalancing support
<DT CLASS="dt-description"><B>protocol</B><DD CLASS="dd-description">PEPt protocol level code
<DT CLASS="dt-description"><B>resolver</B><DD CLASS="dd-description">Internal classes used to support string to object reference
conversion
<DT CLASS="dt-description"><B>servicecontext</B><DD CLASS="dd-description">Internal representation of GIOP ServiceContexts.
<DT CLASS="dt-description"><B>transport</B><DD CLASS="dd-description">PEPt transport level code
<DT CLASS="dt-description"><B>txpoa</B><DD CLASS="dd-description">TSIdentificationImpl, which is used to connect the ORB and
the transaction service.
<DT CLASS="dt-description"><B>util</B><DD CLASS="dd-description">low-level code mostly related to RMI-IIOP.
</DL>
<DT CLASS="dt-description"><B>internal</B><DD CLASS="dd-description">Old (JDK 1.4 and earlier) ORB and JNI library related classes
that we maintain for backward compatibility.
<DT CLASS="dt-description"><B>org/omg</B><DD CLASS="dd-description">Various mostly CSIv2 related protocol definitions (we compile
the CSIv2 IDL in the ORB so that the app server CSIv2 implementation
can use it).
<DT CLASS="dt-description"><B>pept</B><DD CLASS="dd-description">The PEPt 1.0 code used in the ORB.
</DL>
<DT CLASS="dt-description"><B>com/sun/org/omg</B><DD CLASS="dd-description">Some not quite standard OMG classes that were still
in flux in the CORBA 2.4.1 timeframe (these are internal only, so
this doesn't matter much now)
<DT CLASS="dt-description"><B>com/sun/tools/corba/se</B><DD CLASS="dd-description">A number of tools:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>idl</B><DD CLASS="dd-description">The idl compiler
<DT CLASS="dt-description"><B>jmk</B><DD CLASS="dd-description">The tool used to validate .jmk files against the contents of
the source directories
<DT CLASS="dt-description"><B>logutil</B><DD CLASS="dd-description">The source code for the jschemeutil.jar library
<DT CLASS="dt-description"><B>timer</B><DD CLASS="dd-description">XML data for generating timing points
</DL>
</DL>
<DT CLASS="dt-description"><B>orblib/src/share/classes/com/sun/corba/ee</B><DD CLASS="dd-description">Classes in the ORB library.
There are no dependencies from any of this code to classes in the
src hierarchy.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>org</B><DD CLASS="dd-description">Contains the ASM code used in the ORB for dynamic class generation.
<DT CLASS="dt-description"><B>impl/orbutil and spi/orbutil</B><DD CLASS="dd-description">Contains a number of modules:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>argparser(spi only)</B><DD CLASS="dd-description">A general purpose annotation-driven CLI argument
parser.
<DT CLASS="dt-description"><B>closure</B><DD CLASS="dd-description">Simple closure support used in a few placescodegen The runtime
byte code generator library.
<DT CLASS="dt-description"><B>codegen</B><DD CLASS="dd-description">A general-purpose runtime code generation library.
<DT CLASS="dt-description"><B>concurrent</B><DD CLASS="dd-description">Some concurrent queue implementations needed in the new
connection cache.
<DT CLASS="dt-description"><B>copyobject</B><DD CLASS="dd-description">A fast general-purpose object copier.
<DT CLASS="dt-description"><B>file(spi only)</B><DD CLASS="dd-description">A collection of text file utilities used for copyright
header processing and workspace renaming.
<DT CLASS="dt-description"><B>fsm(spi only)</B><DD CLASS="dd-description">Finite State Machine library used in the POA to support
ActiveObjectMap entry semantics. Should be more widely used in ORB
(e.g. connection management). Supports much of the UML state model
(but not nested states, and not petri-net style operations)
<DT CLASS="dt-description"><B>generic(spi_only)</B><DD CLASS="dd-description">Some useful utilities related to Java 5 generic
(generic Pair, various kinds of generic function classes)
<DT CLASS="dt-description"><B>graph(impl only)</B><DD CLASS="dd-description">Some simple graph utilities for computing transitive
closure. Should probably be heavily revised.
<DT CLASS="dt-description"><B>jmx</B><DD CLASS="dd-description">A new framework for using annotation to generate open MBeans
<DT CLASS="dt-description"><B>misc(spi only)</B><DD CLASS="dd-description">odds and ends that don't fit elsewhere
<DT CLASS="dt-description"><B>newtimer</B><DD CLASS="dd-description">A general-purpose timer framework used to capture BEGIN/END
pairs of events.
<DT CLASS="dt-description"><B>proxy(spi only)</B><DD CLASS="dd-description">Utilities related to simplify construction of InvocationHandlers
for java.lang.reflect.Proxy.
<DT CLASS="dt-description"><B>timer(impl only)</B><DD CLASS="dd-description">An old, deprecated timer framework.
<DT CLASS="dt-description"><B>transport</B><DD CLASS="dd-description">The new connection cache implementation (not yet integrated
in the ORB). A nearly identical version of this code is in Grizzly,
and the ORB will eventually use the Grizzly copy.
<DT CLASS="dt-description"><B>threadpool</B><DD CLASS="dd-description">The ORB threadpool implementation that is shared with
the app server (should revisit this in light of JDK 5 executors).
</DL>
</DL>
</DL>
<!--TOC subsection ORB Renaming-->
<H3 CLASS="subsection"><A NAME="htoc7">1.3.3</A> ORB Renaming</H3><!--SEC END -->
Most of the ORB is packaged under the com.sun.corba.ee package. A
version of the ORB code exists in this package (or in a slightly different
version) in every JDK since 1.2. We also deliver the ORB code to the
Sun application server (now project GlassFish). To avoid possibly
collisions between the classes in the JDK and the classes in GlassFish,
we rename all the files in the ORB to the com.sun.corba.ee package.<BR>
<BR>
This rename is done automatically using a Java program (com.sun.corba.ee.spi.orbutil.file.WorkspaceRename)
that is part of the ORB library. There is an ant target (rename) for
this as well. All that is needed for the rename is:
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
cd <workspace>/make
<LI CLASS="li-enumerate">ant orb-library (on a new workspace, to build the orblib.jar the first
time)
<LI CLASS="li-enumerate">ant rename
</OL>
(TBD: make rename do a fast check for the orblib.jar, and build it
if it is not present. Right now, calling ant orb-library takes around
5 seconds, which is too long, since the incremental rename is <1 second).
The ant rename target on a fast local file system should take around
30 seconds or so (much faster than the old scripted version).<BR>
<BR>
Of course, the rename also interferes with the standard edit-compile-test-debug
cycle. I have a build environment built around vim that gets around
this problem, but it is difficult to impossible to deal with renaming
with any IDE that I know of.<BR>
<BR>
The rename is no longer necessary for development in GlassFish-CORBA.
Here all that is required is an ant build, from NetBeans, standalone,
or from any other tool a developer might care to use. The only time
a rename is required is when the jar files are created that are delivered
to GlassFish for integration in the app server.<BR>
<BR>
<!--TOC subsection ORB Build Files-->
<H3 CLASS="subsection"><A NAME="htoc8">1.3.4</A> ORB Build Files<A NAME="sub:ORB-Build-Files"></A></H3><!--SEC END -->
The ORB can only be built with ant. All makefile support has been
removed.<BR>
<BR>
<!--TOC subsubsection Building the ORB-->
<H4 CLASS="subsubsection"><A NAME="htoc9">1.3.4.1</A> Building the ORB<A NAME="sub:Building-the-ORB"></A></H4><!--SEC END -->
The ORB can be build either standalone (the mode used to deliver the
ORB into GlassFish), or as part of the JDK. Here we just focus on
the app server specific build. You MUST use JDK 5 or later.<BR>
<BR>
Assume <ws> is the ORB workspace. The basic build sequence is:
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
cd <ws>/make
<LI CLASS="li-enumerate">ant rename
<LI CLASS="li-enumerate">cd <ws>/build/rename/ee/make
<LI CLASS="li-enumerate">ant build
<LI CLASS="li-enumerate">ant test (or ant emma to run the tests and generate a coverage report)
</OL>
Assuming a local file system is used on a fast machine, the rename
should take around 30 seconds, and the build 60 seconds or less. The
test target builds the tests (build-tests) which takes around 60-90
seconds, and then runs all of the tests, which should take around
40 minutes.<BR>
<BR>
I generally use a script to automate this. It is also possible to
do a build from NetBeans. It used to be necessary to rename in order
to build and run the tests, but that has been fixed in the GlassFish-CORBA
project.<BR>
<BR>
Another small note: it is possible to generate JavaDocs for the CORBA
SPI. To do this, simply go to the make directory in the renamed version
of the workspace, and run “ant javadoc”. The resulting JavaDocs
may then be accessed from <ws>/build/rename/ee/build/release/docs/index.html
(exercise for the reader: fix all of the JavaDoc warnings that show
up). It should also be possible to create the SPI javadocs without
renaming, and the NetBean project supports this as well.<BR>
<BR>
Here is a more detailed description of the ant targets that are useful
to a developer:<BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">Target Name</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Function</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">build</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">builds the ORB library and main ORB code (but not the tests)</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">build-tests</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Runs idlj and rmic on test files, and calls compile-tests</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">compile-tests</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Only compiles the tests (useful if you are changing a test, as build-tests
takes a lot longer to run</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">orb-library</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Just build the ORB library (needed for rename)</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">update-copyright-headers</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Update all copyright headers in the workspace to the contents of make/copyright-information/copyright.txt</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">validate-copyright-headers</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Check that the copyright headers match copyright.txt</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">clean</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Removes all generated files, renamed workspace, and test results</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">clean-emma</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Removes emma results</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">clean-tests</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Removes test results</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">javadoc</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">generate javadocs for ORB SPI (TBD: need to handle ORB library as
well)</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">findbugs</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">generate a findbugs report on the ORB</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">emma</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Runs clean-emma, emma-instr, test, emma-report</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">emma-instr</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Instrument all of the class files so that emma can generate a coverage
report</DIV></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><DIV CLASS="center">emma-report</DIV></TD>
<TD VALIGN=top ALIGN=left><DIV CLASS="center">Generate an emma report (found in <ws>/build/coverage/coverage.html)</DIV></TD>
</TR></TABLE><BR>
There are also a number of targets useful for running tests, which
are discussed in <A HREF="#sec:ORB-Developer-Tests">1.4</A>.<BR>
<BR>
<!--TOC subsubsection Structure of the build files-->
<H4 CLASS="subsubsection"><A NAME="htoc10">1.3.4.2</A> Structure of the build files<A NAME="sub:Structure-of-the"></A></H4><!--SEC END -->
Let's look at the ant files first. There are several .xml files, all
included in build.xml:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>build.xml</B><DD CLASS="dd-description">the main file
<DT CLASS="dt-description"><B>jscheme.xml</B><DD CLASS="dd-description">Ant targets for running jscheme and generating log wrappers
<DT CLASS="dt-description"><B>src-idl.xml</B><DD CLASS="dd-description">Ant targets for generating java from idl for the main
ORB code
<DT CLASS="dt-description"><B>test-idl.xml</B><DD CLASS="dd-description">Ant targets for generating java from idl for the ORB
tests
<DT CLASS="dt-description"><B>test-rmic.sml</B><DD CLASS="dd-description">Ant targets for generating stub and skeletons using
rmic for the ORB tests
<DT CLASS="dt-description"><B>test.xml</B><DD CLASS="dd-description">Ant targets for running the ORB tests.
<DT CLASS="dt-description"><B>emma.xml</B><DD CLASS="dd-description">Ant targets for emma support
<DT CLASS="dt-description"><B>findbugs-filter.xml</B><DD CLASS="dd-description">Used by findbugs to avoid generating bug reports
on either the compilers or third-party code.
</DL>
There are a number of other files as well:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>build.properties</B><DD CLASS="dd-description">Included in build.xml, and used to define the build
version and other information for the maven repository importer (TBD:
this needs testing and integration for GlassFish v3)
<DT CLASS="dt-description"><B>deleted-files.txt</B><DD CLASS="dd-description">A list of generated files that are deleted in
the build, as they are not wanted in the delivery.
<DT CLASS="dt-description"><B>glassfish-corba.pom</B><DD CLASS="dd-description">Part of the maven importer support
<DT CLASS="dt-description"><B>runtest</B><DD CLASS="dd-description">A useful script for running tests as described in <A HREF="#sec:ORB-Developer-Tests">1.4</A>.
</DL>
<!--TOC subsection tests-->
<H3 CLASS="subsection"><A NAME="htoc11">1.3.5</A> tests<A NAME="sub:tests"></A></H3><!--SEC END -->
The ORB has many tests in several different test suites (docs/TestCases.sxc
gives some details of the contents and the numbers of test cases in
the test suites, from a rough manual count). The test suites are:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>ibm</B><DD CLASS="dd-description">Old RMI-IIOP tests created by IBM. These are the hardest tests
to deal with.
<DT CLASS="dt-description"><B>corba</B><DD CLASS="dd-description">The bulk of our developer tests. Covers all areas of the ORB
to some degree.
<DT CLASS="dt-description"><B>pi</B><DD CLASS="dd-description">The Portable Interceptor tests.
<DT CLASS="dt-description"><B>naming</B><DD CLASS="dd-description">Test for the name services.
<DT CLASS="dt-description"><B>mantis</B><DD CLASS="dd-description">Tests specifically for bug fixes made to JDK 1.4.1.
<DT CLASS="dt-description"><B>hopper</B><DD CLASS="dd-description">Tests specifically for bug fixes made to JDK 1.4.2.
<DT CLASS="dt-description"><B>copyobject</B><DD CLASS="dd-description">Tests for the various object copiers. Can also be used
as a timing test for streams, which will likely be very important
to us.
<DT CLASS="dt-description"><B>simpleperf</B><DD CLASS="dd-description">A simple performance test mainly for colocated calls.
</DL>
<!--TOC subsection libraries-->
<H3 CLASS="subsection"><A NAME="htoc12">1.3.6</A> libraries<A NAME="sub:libraries"></A></H3><!--SEC END -->
There are a number of libraries in the lib directory. These are all
used either for building or testing.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>ejb-2_1-api.jar</B><DD CLASS="dd-description">Needed for codegen test
<DT CLASS="dt-description"><B>emma.jar</B><DD CLASS="dd-description">Main emma code
<DT CLASS="dt-description"><B>emma_ant.jar</B><DD CLASS="dd-description">Emma's ant task
<DT CLASS="dt-description"><B>ir.idl</B><DD CLASS="dd-description">Old and obsolete interface repository file (should be deleted)
<DT CLASS="dt-description"><B>japex.jar</B><DD CLASS="dd-description">A version of the Japex performance testing framework (used
for compiling StandardTest)
<DT CLASS="dt-description"><B>jscheme.jar</B><DD CLASS="dd-description">Scheme interpreter used for generating log wrapper source
files
<DT CLASS="dt-description"><B>jschemelogutil.jar</B><DD CLASS="dd-description">Some simple utilities used with JScheme (source
is in the workspace)
<DT CLASS="dt-description"><B>junit.jar</B><DD CLASS="dd-description">JUnit, used for some of the ORB tests
<DT CLASS="dt-description"><B>maven-repository-importer-1.1.jar</B><DD CLASS="dd-description">Part of the maven support for
GlassFish (which is incomplete)
<DT CLASS="dt-description"><B>orb.idl</B><DD CLASS="dd-description">A standard IDL file for some standard definitions (not really
used)
<DT CLASS="dt-description"><B>rt.idl</B><DD CLASS="dd-description">IDL for the CodeBase interface (part of the SendingContext
module; used to enable access to another VM's typing information for
RMI-IIOP)
<DT CLASS="dt-description"><B>testng.jar</B><DD CLASS="dd-description">TestNG, used in some of the ORB tests
</DL>
<!--TOC section ORB Developer Tests-->
<H2 CLASS="section"><A NAME="htoc13">1.4</A> ORB Developer Tests<A NAME="sec:ORB-Developer-Tests"></A></H2><!--SEC END -->
<!--TOC subsection Test Suites-->
<H3 CLASS="subsection"><A NAME="htoc14">1.4.1</A> Test Suites<A NAME="sub:Test-Suites"></A></H3><!--SEC END -->
The ORB developer tests are found in the directories test and optional/test.
The makefile for running the tests is in test/make/Makefile, but the
test suites can also be run from make/Makefile.corba. This table gives
a brief overview of the available test suites:<BR>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD VALIGN=top ALIGN=left>Suite Name</TD>
<TD VALIGN=top ALIGN=left>Test File</TD>
<TD VALIGN=top ALIGN=left>ant target in <BR>
GlassFish-CORBA</TD>
<TD VALIGN=top ALIGN=left>Purpose</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>all</TD>
<TD VALIGN=top ALIGN=left>-</TD>
<TD VALIGN=top ALIGN=left>test-all</TD>
<TD VALIGN=top ALIGN=left>runs all test suites</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>IBM</TD>
<TD VALIGN=top ALIGN=left>test/AllTests.desc</TD>
<TD VALIGN=top ALIGN=left>test-rmi-iiop</TD>
<TD VALIGN=top ALIGN=left>Old IBM tests</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>corba</TD>
<TD VALIGN=top ALIGN=left>corba/CORBATests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-corba</TD>
<TD VALIGN=top ALIGN=left>Most of the newer tests</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>pi</TD>
<TD VALIGN=top ALIGN=left>pi/PITests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-pi</TD>
<TD VALIGN=top ALIGN=left>Portable Interceptors tests</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>copyobject</TD>
<TD VALIGN=top ALIGN=left>corba/CopyObjectTests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-copyobject</TD>
<TD VALIGN=top ALIGN=left>copyobject test</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>naming</TD>
<TD VALIGN=top ALIGN=left>naming/NamingTests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-naming</TD>
<TD VALIGN=top ALIGN=left>naming tests</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>hopper</TD>
<TD VALIGN=top ALIGN=left>hopper/HopperTests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-hopper</TD>
<TD VALIGN=top ALIGN=left>Bugfixes for JDK 1.4.1</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>mantis</TD>
<TD VALIGN=top ALIGN=left>mantis/MantisTests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-mantis</TD>
<TD VALIGN=top ALIGN=left>Bugfixes for JDK 1.4.2</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left>simpleperf</TD>
<TD VALIGN=top ALIGN=left>performance/Tests.tdesc</TD>
<TD VALIGN=top ALIGN=left>test-perf</TD>
<TD VALIGN=top ALIGN=left>co-located call performance test</TD>
</TR></TABLE><BR>
All of the tests are run from <ws>/make using the appropriate targets.
The output of the tests (stdout and stderr) are redirected to log
files. These log files are located in <ws>/test/make/gen, under the
package name of the individual tests in the test suite. Most of the
tests of interest are in the corba test suite, so making those pass
first is usually all that is needed (the others tend to pass too,
once the CORBA tests pass). This is not always the case, particularly
if you are working on the RMI-IIOP code (which is tested in the IBM
test suite). These tests are also descibed briefly in <ws>/docs/TestCases.sxc,
which is a spreadsheet that roughly counts the number of test cases
in each test in each test suite.<BR>
<BR>
Each of the tests in the test suite starts one or more Controllers.
A Controller is simply a class that controls a component of a test.
For example, many of the tests have 3 controllers: a Client, a Server,
and ORBD (which is used mainly for name service, as few tests actually
exercise server activation).<BR>
<BR>
Adding a new test is simple: just create a new package for testing,
write the test, and add it to the appropriate test file. There is
a document that is somewhat helpful in the workspace at
<DIV CLASS="flushleft"><DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><TT>
test/src/share/classes/corba/framework/package.html
</TT></DL></DIV>
Especially read the section on the Controller classes, as that is
really the heart of the test framework. However, the document is old,
and somewhat out of date. You should consider the following additions
and changes since the document was written:
<UL CLASS="itemize"><LI CLASS="li-itemize">
You can use JUnit for tests. Simple write a JUnit test, and then wrap
it with a simple test class that extends corba.framework.CORBATest.
In fact, ANY program can be included in the CORBA test framework this
way. All that is needed is for the embedded test to indicate success
by returning 0, and failure by return a positive value in a System.exit()
call.<BR>
<BR>
The following tests currently use JUnit:
<UL CLASS="itemize"><LI CLASS="li-itemize">
corba/copyobject (this is the most complex example of what can be
done with JUnit)
<LI CLASS="li-itemize">corba/dynamicrmiiiop
<LI CLASS="li-itemize">corba/stubserialization
<LI CLASS="li-itemize">corba/misc (this is a good test to use a simple example)
<LI CLASS="li-itemize">corba/messagetrace
<LI CLASS="li-itemize">corba/codegen
</UL>
<LI CLASS="li-itemize">Similarly, you can also use TestNG for tests. The following tests
use TestNG:
<UL CLASS="itemize"><LI CLASS="li-itemize">
corba/timer
<LI CLASS="li-itemize">corba/mixedorb
<LI CLASS="li-itemize">corba/jmx
<LI CLASS="li-itemize">corba/nortel
<LI CLASS="li-itemize">corba/simpledynamic
<LI CLASS="li-itemize">corba/mixedorb
<LI CLASS="li-itemize">corba/connectioncache
</UL>
<LI CLASS="li-itemize">The ant build needs to be updated if new tests that require IDL or
RMIC are needed. See test-idl.xml and test-rmic.xml to see how this
is handled.
<LI CLASS="li-itemize">You can write tests that use RMI-IIOP without needing rmic. To do
this, just use dynamic RMI-IIOP. For an example of how to do this,
look at the corba/rfm test. Basically you just need to use the PresentationManager
API for a couple of things (access to the repository ID and to create
a Tie), and you also need to make sure that dynamic RMI-IIOP is enabled.
A renamed test will automatically run under dynamic RMI-IIOP, but
if the test is NOT renamed (and this will be the case after the migration
to GlassFish, at least for pure ORB development), you need to add
the following static initializer to the test code:
</UL>
<DIV CLASS="flushleft"><DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><TT>
static {
</TT><DIV CLASS="flushleft"><DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><TT>
System.setProperty( ORBConstants.USE_DYNAMIC_STUB_PROPERTY, “true” ) ;
</TT></DL></DIV><TT>
}
</TT></DL></DIV>
<UL CLASS="itemize"><LI CLASS="li-itemize">
Conversion status info is out of date in the corba/framework/package.html
document: ignore this section.
<LI CLASS="li-itemize">Debugging is better. The document mentions the RDebugExec controller
(and also ODebugExec, but the omniscient debugger has not been tested
or updated in years. See http://www.lambdacs.com/debugger/debugger.html
for more information).
<LI CLASS="li-itemize">Default ORB class has changed. We now use com.sun.corba.ee.impl.orb.ORBImpl.
<LI CLASS="li-itemize">There are two security policy files available for running the tests.
The default test.policy file simply sets up the needed permissions
for all of the tests and the ORB. The more fine grained test.policy.secure
file sets up more restrictive permissions for the tests, while giving
more powerful permissions to the ORB code in the build and optional/build
directories. Which policy file is used is set in the test/make/Makefile
in the DEFINES macro.<BR>
<BR>
Setting the more secure policy file is useful to work on ensuring
that the ORB has doPrivileged blocks around all operations that have
security implications. It is known that the ORB is at least somewhat
deficient in this area, but we have not taken the time to thoroughly
address this issue.<BR>
<BR>
<LI CLASS="li-itemize">There are several environment variables that are useful to set while
running tests (see test/make/Makefile for more details):
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>STATIC_STUB</B><DD CLASS="dd-description">when set to 1, forces the use of static RMI-IIOP
<DT CLASS="dt-description"><B>DYNAMIC_STUB</B><DD CLASS="dd-description">when set to 1, forces the use of dynamic RMI-IIOP
<DT CLASS="dt-description"><B>BCEL_COPYOBJECT</B><DD CLASS="dd-description">when set to 1, uses the BCEL version of the fast
object copier (experimental)
<DT CLASS="dt-description"><B>JAVA_SERIALIZATION</B><DD CLASS="dd-description">when set to 0, use CDR instead of JSG (JSG is
experimental, but enabled by default in the workspace only)
<DT CLASS="dt-description"><B>DEBUGGER</B><DD CLASS="dd-description">can be set as follows:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>1</B><DD CLASS="dd-description">Set ORBDebugForkedProcess=true (for IBM tests), and run tests
so that a JPDA-compliant debugger can be attached
<DT CLASS="dt-description"><B>2</B><DD CLASS="dd-description">Run tests under OptimizeIt
<DT CLASS="dt-description"><B>3</B><DD CLASS="dd-description">Run tests withc -Djcov=true for coverage analysis
</DL>
</DL>
</UL>
<!--TOC subsection debugging tests-->
<H3 CLASS="subsection"><A NAME="htoc15">1.4.2</A> debugging tests<A NAME="sub:debugging-tests"></A></H3><!--SEC END -->
To debug a test, you need to know the name of the controller(s) to
which you need to attach a debugger. Controllers are normally created
by the methods createORBD, createClient, and createServer. The default
names of the controllers are ORBD, Client, and Server, respectively.
The createClient and createServer methods can also take a second argument
(the first is the class name of the test program) that gives a specific
name for the controller.<BR>
<BR>
Given the name of the controller(s) to debug, simply add the argument
<DIV CLASS="flushleft"><DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><TT>
-rdebug XXX,YYY
</TT></DL></DIV>
for controllers XXX and YYY (for example) to the end of the test file
argument that starts the test.<BR>
<BR>
ORB debug flags can also be passed into a test. To do this, add the
argument
<DIV CLASS="flushleft"><DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><TT>
-orbtrace XXX:f1,f2;YYY:f3
</TT></DL></DIV>
where the argument is a semi-colon separated. Each element of this
list starts with a controller name, followed by a comma separated
list of ORB debug flag names (see com.sun.corba.ee.spi.orb.ORB for
the current list).<BR>
<BR>
It is also possible to change the log levels so that ORB log information
can be displayed on the console (or anywhere else, depending on the
log system configuration). This follows the usual log system mechanisms.
The ORB logger names are discussed in sec:ORB-Logging.<BR>
<BR>
<!--TOC subsection Debugging and Running a single test-->
<H3 CLASS="subsection"><A NAME="htoc16">1.4.3</A> Debugging and Running a single test</H3><!--SEC END -->
I recently added the capability to run and debug a single test. This
requires the runtest script in the make directory. This is a script
that calls the run-test-target target in the test.xml file. You can
give runtest any arguments that occur in the .tdesc files. To use
runtest, cd to <ws>/make and check that runtest is executable. Here
are a few examples (assuming the current directory is <ws>/make):
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
To run the codegen test:<BR>
./runtest -test corba.codegen.CodegenTest
<LI CLASS="li-enumerate">To attach a debugger to the client controller in the codegen test:<BR>
./runtest -test corba.codegen.CodegenTest -rdebug client
<LI CLASS="li-enumerate">To see the transport debug output on the evol_client controller in
the corba EvolveTest:<BR>
./runtest -test corba.evolve.EvolveTest -orbtrace evol_client:transport<BR>
(the debug output will be in ../test/make/gen/corba/evolve/evol_client.out.txt)
</OL>
All tests are run in the environment of the current ORB workspace.
Either the renamed or the non-renamed version can be used. This is
important because JDK 5 or later contains many of the same classes
in the com.sun.corba packages as the workspace. The ant files set
up the java -Xbootclasspath argument correctly so that the versions
of the com.sun.corba classes in the workspace are used, instead of
those in the JDK.<BR>
<BR>
<!--TOC section ORB SQE Tests-->
<H2 CLASS="section"><A NAME="htoc17">1.5</A> ORB SQE Tests<A NAME="sec:ORB-SQE-Tests"></A></H2><!--SEC END -->
Sony Manuel maintains a large collection of CORBA SQE tests in /java/idl/ws/rip/RIP_TEST_MASTER.
Read the file DTF_RTM_README.html in this workspace for details
(and contact Sony as well). These test are not currently available
in GlassFish-CORBA.<BR>
<BR>
We should look at creating a tighter integration between the CORBA
dev tests and the SQE tests at some point. In particular, I'd like
to have the POA and INS tests run automatically as part of the CORBA
dev test cycle.<BR>
<BR>
<!--TOC section Thoughts on Middleware goals-->
<H2 CLASS="section"><A NAME="htoc18">1.6</A> Thoughts on Middleware goals<A NAME="sec:Thoughts-on-Middleware"></A></H2><!--SEC END -->
Middleware is a rather complex kind of software to build well. It
spans many parts of the computer science discipline, including compilers,
operating systems, and network communications. Middleware tends to
be complex, long-lived software, and there are many different ways
to build it. Our goal in developing the ORB has been to develop very
flexible and high-performance middleware while maintaining a clear
(if complex) architecture that can be easily composed, ultimately
out of re-usable modules. One way to look at an ORB is that ORB.init
creates a particular middleware implementation that is specialized
to the needs of an application. For example, the behavior of the default
ORB in the JDK is rather different from that of the ORB in the app
server, even though both share >95% of the same code.<BR>
<BR>
At least the following dimensions must be considered in order to build
effective middleware:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>Flexibility.</B><DD CLASS="dd-description">Middleware has been changing constantly since Nelson
invented RPC around 1980 or so. Much of Harold's work on PEPt has
been devoted to dealing effectively with this aspect of middleware
construction. The following elements often vary indendently of each
other:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>Presentation.</B><DD CLASS="dd-description">By this we mean the kinds of data types that may be
passed between a client and server (roles here, as any given software
entity often acts in both roles), and the APIs and other structures
used to collect these kinds of data together. <BR>
<BR>
Examples of data types include the IDL data model from CORBA, the
Java data model from RMI, XML schema, ASN.1, SUN RPC, MIME types,
and many others. <BR>
<BR>
There are broadly speaking two ways to view the API question: either
the system uses some sort of Proxy to make a remote call “look
like” a call to an abstraction (method call, procedure call, SmallTalk
message send, etc) or the API provides an explicit representation
of a request or message that a program can set up with data and then
send (CORBA dynamic invocation, Message Oriented Middleware, and others).<BR>
<BR>
<DT CLASS="dt-description"><B>Encoding.</B><DD CLASS="dd-description">Given a structure containing the data from the presentation
layer, it needs to be converted from an in memory representation to
some representation suitable for transmitting across some serial medium
like a TCP connection. This is usually referred to as marshalling
and unmarshalling the data, and is often the most expensive operation
that middleware performs. In fact, I believe this is the most significant
challenge for middleware of all types as network hardware increases
in speed.
<DT CLASS="dt-description"><B>Protocol.</B><DD CLASS="dd-description">This is related to but distinct from encoding. Here we
are concerned about the kinds of messages that clients and servers
exchange. This is mainly about message framing, headers, various kinds
of meta-data associated with requests, and the distributed state machines
involved in protocol design.
<DT CLASS="dt-description"><B>Transport.</B><DD CLASS="dd-description">Ultimately, some mechanism must be used to transmit data
from the client to the server. This can include network protocols,
shared memory mechanisms, Solaris doors, and direct calls within the
same address space that bypass all such mechanisms (in which case
the protocol and encoding are much simplified as well).
</DL>
<DT CLASS="dt-description"><B>Performance.</B><DD CLASS="dd-description">Everyone always wants middleware to perform as quickly
as possible. This is quite a challenge. First, there are many aspects
to performance, including:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>Latency.</B><DD CLASS="dd-description">How long does it take to send messages of various types?
What about short vs. very long messages?
<DT CLASS="dt-description"><B>Throughput.</B><DD CLASS="dd-description">How many request per second can be sent through the
system? This often conflicts with latency. For example, a front end
concentrator can help to pump more data through, at the cost of increased
latency due to an extra hop.
<DT CLASS="dt-description"><B>Creating Endpoints.</B><DD CLASS="dd-description">Object-Oriented remoting systems like CORBA
create, marshal, and unmarshal endpoints (IORs in CORBA) constantly,
and the performance of such operations is quite significant.
</DL>
Today, our latency is poor (except for co-located RMI-IIOP calls,
which are highly optimized), our throughput is OK (and this is NIO
select related), and the IOR handling is pretty good, although much
more is possible.<BR>
<BR>