Produced by Araxis Merge on 7/6/2017 8:22:51 PM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.
| # | Location | File | Last Modified |
|---|---|---|---|
| 1 | OSCIF_CTT_v4_build 1.zip\ISAAC-developer-docs | README.md | Wed May 31 03:55:50 2017 UTC |
| 2 | OSCIF_CTT_v4_build 1.zip\ISAAC-developer-docs | README.md | Mon Jul 3 21:34:11 2017 UTC |
| Description | Between Files 1 and 2 |
|
|---|---|---|
| Text Blocks | Lines | |
| Unchanged | 6 | 396 |
| Changed | 5 | 10 |
| Inserted | 0 | 0 |
| Removed | 0 | 0 |
| Whitespace | |
|---|---|
| Character case | Differences in character case are significant |
| Line endings | Differences in line endings (CR and LF characters) are ignored |
| CR/LF characters | Not shown in the comparison detail |
No regular expressions were active.
| 1 | # ISAAC-de veloper-do cs | |
| 2 | A reposito ry for sto ring basic developer oriented documentat ion about the suite of ISAAC p rojects | |
| 3 | ||
| 4 | Note that the purpos e of this repository is not to provide d esign docu mentation for ISAAC. Rather, this proje ct is | |
| 5 | intended t o be a sim ple, conci se set of documentat ion that i s geared t oward deve lopers tha t are tryi ng to buil d | |
| 6 | the ISAAC suite of s oftware. | |
| 7 | ||
| 8 | If you nee d a summar y of the t ypes of ch anges that have occu rred with the migrat ion away f rom the OT F APIs, se e | |
| 9 | https://gi thub.com/V A-CTT/ISAA C-develope r-docs/blo b/master/O TFMigratio n.md | |
| 10 | ||
| 11 | ##Running Komet Loca lly | |
| 12 | See https: //github.c om/VA-CTT/ ISAAC-deve loper-docs /blob/mast er/Komet.m d | |
| 13 | ||
| 14 | ##Requirem ents | |
| 15 | ISAAC requ ires moder n supporti ng softwar e - this m eans Java 8, and Mav en 3.x or newer. | |
| 16 | ||
| 17 | ##Projects | |
| 18 | Currently, there are 6 related projects - each wit h its own repository - each in dependentl y versione d. Note, the order here is al so the ord er | |
| 19 | the projec ts need to be built in, if you want to b uild the e ntire code stack. | |
| 20 | ||
| 21 | - ISAAC-de veloper-do cs - https ://github. com/VA-CTT /ISAAC-dev eloper-doc s.git | |
| 22 | - This p roject - d eveloper d ocumentati on | |
| 23 | - ISAAC - https:// DNS : PORT /git/summa ry/ISAAC.g it | |
| 24 | - Lowest level ISA AC code. Contains a ll APIs, a nd impleme ntations - but no GU I code. | |
| 25 | - ISAAC-te rm-convert -rf2 - htt ps:// DN S :PORT | |
| 26 | - Code b uilt on to p of ISAAC that enab les the tr anslation of RF2 for matted con tent into the native ISAAC for mat. Note that this project | |
| 27 | is not typically part of a n ISAAC en d user app lication - this is o nly used t o translat e RF2 nati ve format into ISAAC native fo rmat. | |
| 28 | - ISAAC-db -builder-s olor - htt ps:// DN S :PORT | |
| 29 | - An exa mple proje ct that ta kes in a c ollection of nativel y formatte d ISAAC da ta files, and builds a databas e out of t hem. | |
| 30 | This p articular example co mbines the ISAAC bas e metadata and Snome dCT. Note that this project i s not typi cally part of an ISA AC end | |
| 31 | user a pplication - this is only used to create an ISAAC database o ut of a se ries of IS AAC native formated files. | |
| 32 | - ISAAC-fx -gui - htt ps://DNS :PORT | |
| 33 | - A Java FX GUI for ISAAC | |
| 34 | - ISAAC-fx -gui-pa - https://DN S :PORT | |
| 35 | - An exa mple *Asse mbly* proj ect that s hows how t o create a n end-user applicati on out of ISAAC, a d atabase, a nd the ISA AC-fx-gui. | |
| 36 | While this proje ct contain s no code, it contai ns the con figuration for the a ssembly (t hings like users, ch ange set r epository location, etc) | |
| 37 | and th e dependen cy set for the GUI ( which GUI components should be included in the app lication). It also contains t he configu ration for which | |
| 38 | databa se should be package d with the GUI, and the instal ler config uration. The end re sult of bu ilding thi s project is a GUI a pplication for | |
| 39 | the en d user - w hich inclu des all ne cessary co mponents f rom the st ack above. | |
| 40 | ||
| 41 | ||
| 42 | The GitHub repositor ies are th e primary 'work' rep ositories for develo pment. | |
| 43 | **This is where deve lopers sho uld push t heir work. ** | |
| 44 | ||
| 45 | ##Maven Bu ild Mangem ent | |
| 46 | Each proje ct is mana ged and bu ilt by Mav en. Most projects a re multi-m odule proj ects thems elves, hav ing multip le modules . | |
| 47 | ||
| 48 | In general , the nece ssary exte rnal depen dencies to build the ISAAC sui te should all be ava ilable on public rep ositories. However, the termi nology | |
| 49 | files used by the se rver are n ot publicl y availabl e. | |
| 50 | ||
| 51 | See also * *[artifact server](h ttps://git hub.com/VA -CTT/ISAAC -developer -docs/tree /master/Ma venConfig. md)** | |
| 52 | ||
| 53 | ||
| 54 | ##Utility Scripts | |
| 55 | A few util ity script s are avai lable in t he **[scri pts](https ://github. com/VA-CTT /ISAAC-dev eloper-doc s/tree/mas ter/script s)** sub-f older. Th e scripts published | |
| 56 | so far are all [pyth on](https: //www.pyth on.org/) s cripts whi ch aid in management of all of the proje cts that m ake up the ISAAC sui te. | |
| 57 | ||
| 58 | To use the se scripts , copy the m into the same fold er that co ntains all of your c hecked out ISAAC pro jects (lik ely, the p arent fold er of this project) | |
| 59 | ||
| 60 | - cloneAll .py - Exec utes **git clone --b ranch 'bra nchname'** to pull d own all of the proje ct code fr om GitHub | |
| 61 | ||
| 62 | - buildISA AC.py - Ex ecutes **m vn -e clea n install* * or **mvn -e clean package** on each pr oject *in the correc t order* t o effect a complete build of t he entire | |
| 63 | ISAAC suit e. | |
| 64 | ||
| 65 | - cleanISA AC.py - Ex ecutes **m vn clean** on each p roject to recover di sk space | |
| 66 | ||
| 67 | - fetchAll .py - Exec utes **git fetch** o n each pro ject | |
| 68 | ||
| 69 | ||
| 70 | ##Developm ent Notes | |
| 71 | Developers that are focusing o n ISAAC de velopment (and not h andling co ntent impo rt) typica lly only n eed: | |
| 72 | - ISAAC | |
| 73 | - ISAAC-fx -gui | |
| 74 | - ISAAC-fx -gui-pa | |
| 75 | ||
| 76 | ||
| 77 | ##Eclipse Configurat ion Notes | |
| 78 | Eclipse 4. 4 or newer is requir ed for Jav a 8 suppor t. Eclips e 4.5 or n ewer is hi ghly recom mended. | |
| 79 | ||
| 80 | **It is HI GHLY recom mended tha t you buil d on the c ommand lin e with jus t maven be fore tryin g to bring these pro jects into Eclipse** | |
| 81 | ||
| 82 | Eclipse [M 2E](http:/ /eclipse.o rg/m2e/) s upports mo st aspects of our ma ven config uration fi les. | |
| 83 | ||
| 84 | ###Importi ng Project s | |
| 85 | The defaul t integrat ion of Git into ecli pse does n ot clone i nto the wo rkspace fo lder. It is easier to work wi th the pro jects if y ou change this (if y ou are clo ning from within ecl ipse). | |
| 86 | ||
| 87 | In Window -> Prefere nces -> Te am -> Git -> Default repositor y folder: - change t hat to you r workspac e location or **${wo rkspace_lo c}** | |
| 88 | ||
| 89 | Then: | |
| 90 | ||
| 91 | - Clone th e projects you want to work on with Git - do not i mport into the works pace yet. | |
| 92 | - Import - > Maven -> Existing Maven Proj ects | |
| 93 | - Select the proje ct that yo u checked out | |
| 94 | - It is also usefu l to "Add projet(s) to working set" at t he time th at you do the import to aid in organizat ion. | |
| 95 | ||
| 96 | In the pac kage explo rer, you c an then ch oose "Top Level Elem ents" from the 'Tria ngle' drop down menu , and chan ge it to " Working Se ts". This will | |
| 97 | give you a much bett er hierarc hical view of the ma ven projec t structur es. | |
| 98 | ||
| 99 | ###M2E Lif ecycle iss ues | |
| 100 | You should install a ny M2E plu gins that are availa ble to han dle lifecy cle config urations, so that th ings such as JaxB co de generat ion work | |
| 101 | correctly. The pom files alre ady contai n sections that shou ld prevent errors fo r lifecycl e issues t hat m2e ca nnot handl e. | |
| 102 | ||
| 103 | ||
| 104 | ###Eclipse and jaxb2 | |
| 105 | The jaxb2 plugin for Eclipse d oes not wo rk properl y if your eclipse wa s launched using a J RE. | |
| 106 | ||
| 107 | If you get an error like this: | |
| 108 | ||
| 109 | ``` | |
| 110 | Execution default of goal org. jvnet.jaxb 2.maven2:m aven-jaxb2 -plugin:0. 12.3:gener ate failed : A requir ed class w as | |
| 111 | missing wh ile execut ing org.jv net.jaxb2. maven2:mav en-jaxb2-p lugin:0.12 .3:generat e: com/sun /xml/bind/ api/ErrorL istener | |
| 112 | ``` | |
| 113 | ||
| 114 | You need t o reconfig ure eclips e to launc h with a J DK. The e asiest way to do thi s is to ed it the fil e **eclips e.ini**. Add a **-v m** parame ter, as sh own here: | |
| 115 | ||
| 116 | ``` | |
| 117 | -startup | |
| 118 | plugins/or g.eclipse. equinox.la uncher_1.3 .0.v201404 15-2008.ja r | |
| 119 | -vm | |
| 120 | C:\Program Files\Jav a\jdk1.8.0 _65\bin\ja vaw.exe | |
| 121 | --launcher .library | |
| 122 | plugins/or g.eclipse. equinox.la uncher.win 32.win32.x 86_64_1.1. 200.v20150 204-1316 | |
| 123 | -product | |
| 124 | ``` | |
| 125 | ||
| 126 | ###Maven W orkspace R esolution | |
| 127 | Sometimes when you i mport proj ects into Maven, it imports th em with "W orkspace R esolution" disabled. This can lead to e rroneous e rrors abou t not bein g able to resolve | |
| 128 | other modu les which are presen t in the s ame eclips e workspac e. Make s ure Maven -> Enable Workspace Resolution is toggle d. To bul k update, enable wor kspace res olution, | |
| 129 | then delet e, and rei mport all of the pro jects as m aven proje cts. | |
| 130 | ||
| 131 | ###Eclipse and JavaF X warnings | |
| 132 | ||
| 133 | Eclipse cu rrently ha s bugs in dealing wi th JavaFX code - and will prod uce copiou s warnings on classe s that inv olve JavaF X librarie s. This i ssue can b e | |
| 134 | fixed temp orarily as documente d here: h ttps://bug s.eclipse. org/bugs/s how_bug.cg i?id=43106 7#c9 | |
| 135 | ||
| 136 | Alternativ ely, insta ll the e(f x)clipse I DE plugins for eclip se. | |
| 137 | ||
| 138 | ###Launchi ng ISAAC f rom Eclips e | |
| 139 | Launching ISAAC from within Ec lipse is m ost easily done by c reating a run config uration in the **fx- gui-assemb ly** proje ct. | |
| 140 | ||
| 141 | The main m ethod is * *gov.va.is aac.gui.IS AACFxGUI** . Eclipse sometimes doesn't r ead the ma ven classp ath proper ly when co nfiguring a run conf iguration. If this | |
| 142 | happens, simply add **most** of the ISA AC project s on the c lasspath t ab of the Run Config uration. | |
| 143 | ||
| 144 | **What to skip:** To make sure the loggi ng configu ration com es up prop erly, do * *NOT** inc lude the p roject **o chre-mojo- log-config **. Addit ionally, m ake | |
| 145 | sure that the projec t **fx-gui -config** is the fir st project in your c lasspath r esolution order. Th is will en sure that log4j find s the corr ect config uration fi le. | |
| 146 | ||
| 147 | Finally, y ou need a datastore. Upon sta rtup, ISAA C will try to locate the DB in the folde r the JVM was launch ed from. It is typi cally easi est to | |
| 148 | place a co py of the ISAAC data store with in the ISA AC-fx-gui- pa/fx-gui- assembly f older - re sulting in this hier archy: | |
| 149 | ||
| 150 | ``` | |
| 151 | ISAAC-fx-g ui-pa | |
| 152 | - fx-gui -assembly | |
| 153 | - snom ed-2015073 1-1.0-SNAP SHOT-all.d ata | |
| 154 | + ME TA-INF | |
| 155 | + ob ject-chron icles | |
| 156 | + se arch | |
| 157 | ``` | |
| 158 | ||
| 159 | You can ob tain a dat astore usi ng one of the follow ing option s: | |
| 160 | - **mvn c lean packa ge** the p roject ISA AC-fx-gui- pa using m aven. Whe n the buil d complete s, a datas tore will be located in the | |
| 161 | ISAAC-f x-gui-pa\f x-gui-asse mbly\targe t folder. Move this datastore folder up one folde r. | |
| 162 | - Build a datastore using a p roject lik e ISAAC-db -builder-s olor - mo ve the res ulting dat astore fro m the ISAA C-db-build er-solor * target* su bfolder. | |
| 163 | ||
| 164 | ||
| 165 | ##Required HEAP size for runni ng with a DB | |
| 166 | ISAAC curr ently requ ires at le ast 5 GB o f java HEA P to run w ith the fu ll SNOMED database. To run wi th the ful l SOLOR da tabase, yo u need at least | |
| 167 | 6 GB of HE AP. Unles s your sys tem has mo re than 24 GB of RAM , the defa ult JVM ma x for the HEAP will be inadequ ate - as t he JVM sel ects 1/4 o f your | |
| 168 | RAM as the default m ax. | |
| 169 | ||
| 170 | Furthermor e, two oth er options (below) f urther imp rove perfo rmance. | |
| 171 | ||
| 172 | The recomm ended conf iguration to pass in to the JVM launch is : | |
| 173 | ||
| 174 | ``` | |
| 175 | -Xmx6g -XX :+UseG1GC -XX:Metasp aceSize=10 0M | |
| 176 | ``` | |
| 177 | ||
| 178 | Setting a larger HEA P size is encouraged , if you h ave a prop er develop ment syste m :) | |
| 179 | ||
| 180 | The G1GC s etting ena bles a new er garbage collector that does a better job at pre venting lo ng pauses in the GUI . The Met aspaceSize parameter is requir ed | |
| 181 | to prevent a long pa use during the initi al usage o f the GUI. These pa rameters a re automat ically set when an e nd user in stalls ISA AC, and ar e included in | |
| 182 | the comman d-line lau nch script s. It is only when running wi thin an ID E environm ent that y ou need to manually specify th em. | |
| 183 | ||
| 184 | ##Logging Configurat ion | |
| 185 | The loggin g system i s configur ed by the file **ISA AC-fx-gui- pa/fx-gui- config/src /main/reso urces/log4 j2.xml**. By defaul t, two log files are produced - | |
| 186 | isaac.log and isaac- debug.log. These wi ll appear in the fol der where the JVM wa s launched from (typ ically ISA AC-fx-gui- pa/fx-gui- assembly). | |
| 187 | ||
| 188 | To configu re so that debug or info level logging a ppears on the consol e for deve lopment pu rposes, un comment th e followin g lines in the log4j 2.xml file : | |
| 189 | ||
| 190 | ``` | |
| 191 | <!--Ap penderRef ref="STDOU T-DEBUG" / --> | |
| 192 | <!--Ap penderRef ref="STDOU T-INFO" /- -> | |
| 193 | ``` | |
| 194 | ||
| 195 | ##JavaFX a nd Windows 10 | |
| 196 | JavaFX doe sn't work properly o n Windows 10 with ha rdware ren dering - a t least no t on my ha rdware. O racle / Ja vaFX devel opers are tone-deaf to the pro blem. | |
| 197 | ||
| 198 | Specify th e followin g VM argum ent to dis able the h ardware re nding pipe line: | |
| 199 | ||
| 200 | ``` | |
| 201 | -Dprism.or der=sw | |
| 202 | ``` | |
| 203 | this will allow you to use Jav aFX |
Araxis Merge (but not the data content of this report) is Copyright © 1993-2016 Araxis Ltd (www.araxis.com). All rights reserved.