69. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 9/24/2019 1:37:57 PM Eastern 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.

69.1 Files compared

#	Location	File	Last Modified
1	PCL-5_v1_build_8.zip\v1_build 8\Unredacted\spp_mha_web-development.zip\spp_mha_web-development\Docs\vistalink	vistalink_1_6_dg.doc	Wed Jul 31 17:35:31 2019 UTC
2	PCL-5_v1_build_8.zip\v1_build 8\Unredacted\spp_mha_web-development.zip\spp_mha_web-development\Docs\vistalink	vistalink_1_6_dg.doc	Tue Sep 24 16:49:38 2019 UTC

69.2 Comparison summary

Description	Between Files 1 and 2
Description	Text Blocks	Lines
Unchanged	14	3492
Changed	13	73
Inserted	0	0
Removed	2	53

69.3 Comparison options

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

69.4 Active regular expressions

No regular expressions were active.

69.5 Comparison detail




1
2	VISTALINK
3	DEVELOPER GUIDE
4	Version 1. 6
5	December 2 010
6	Department of Vetera ns Affairs
7	Office of Informatio n and Tech nology
8	Product De velopment
9	Revision H istory
10	DateDescri ptionAutho r12/03/10V istALink V ersion 1.6 release.P roduct Dev elopment S ervices Se curity Pro gram VistA Link devel opment tea m.
11	Albany, NY OIFO:
12	Developer— Mike Kilma de
13	Developer— Liz Defiba ugh
14	Bay Pines, FL OIFO:
15	Developmen t Manager— Charles Sw artz
16	Tester—Jas on Woodyar d
17	Oakland, C A OIFO:
18	Developer— Kyle Clark e
19	SQA—Gurbir Singh
20	Technical Writer—Sus an Strack0 5/2006Init ial VistAL ink Versio n 1.5 rele ase.Jim Al exander, t echnical w riter
21	Dawn Clark , project managerTab le i. Revi sion Histo ry
22	Contents
23	iiRevision History
24
25
26	viiTables and Figure s
27
28
29	ixOrientat ion
30
31
32	ixTerminol ogy
33
34
35	ixText Con ventions
36
37
38	1-11.
39	Introducti on
40
41
42	1-11.1.
43	About this Guide
44
45
46	1-11.2.
47	WebLogic U pdates Pro ject
48
49
50	1-11.3.
51	About J2EE Connector s
52
53
54	1-11.4.
55	Public Vis tALink API s Document ation
56
57
58	1-21.5.
59	Sample App lications for J2EE S erver
60
61
62	1-21.6.
63	Deprecated VistALink APIs
64
65
66	2-12.
67	Developer Workstatio n Setup
68
69
70	2-12.1.
71	J2EE Devel opment
72
73
74	2-12.1.1.
75	IDE
76
77
78	2-12.1.2.
79	J2EE Runti me
80
81
82	2-12.2.
83	J2SE Devel opment
84
85
86	2-12.2.1.
87	IDE
88
89
90	2-12.2.2.
91	J2SE Runti me
92
93
94	3-13.
95	How to Use VistALink in J2EE A pplication s
96
97
98	3-13.1.
99	Using Stat ion Number and Divis ion
100
101
102	3-13.1.1.
103	System Loc ator: Inst itution-Co nnector Ma pping
104
105
106	3-23.1.2.
107	Multidivis ion-Aware Applicatio n Code: Co nnectionSp ec Credent ials
108
109
110	3-23.1.3.
111	Example
112
113
114	3-23.2.
115	Request Cy cle
116
117
118	3-23.2.1.
119	Retrieving the Conne ction Fact ory
120
121
122	3-33.2.2.
123	Instantiat ing a Conn ection Spe c for Re-a uthenticat ion
124
125
126	3-43.2.3.
127	Getting a Connection (Connecti on Spec)
128
129
130	3-43.2.4.
131	Executing a Request
132
133
134	3-43.2.5.
135	Closing th e Connecti on
136
137
138	3-53.2.6.
139	Complete R equest Cyc le
140
141
142	3-63.2.7.
143	Connectivi ty Failure s and Retr y Strategi es
144
145
146	3-63.3.
147	More about Re-authen tication
148
149
150	3-63.3.1.
151	Overview
152
153
154	3-73.3.2.
155	Connection Specifica tion Class es
156
157
158	3-73.3.3.
159	Institutio n/Division Rules for Re-authen tication
160
161
162	3-83.3.4.
163	Applicatio n Proxy Us er
164
165
166	3-103.4.
167	Timeouts
168
169
170	3-103.4.1.
171	Socket-Lev el Forced Timeout
172
173
174	3-113.4.2.
175	Graceful ( Request-Le vel) Timeo ut
176
177
178	3-133.5.
179	Institutio n Mapping
180
181
182	3-143.5.1.
183	How to Con figure Map pings
184
185
186	3-143.5.2.
187	How to Vie w the Curr ently Load ed Mapping s
188
189
190	3-143.5.3.
191	Retrieving Mappings for Applic ations
192
193
194	3-143.5.4.
195	Subdivisio ns
196
197
198	3-153.6.
199	VistALink Java API R eference
200
201
202	4-14.
203	Executing Requests
204
205
206	4-14.1.
207	Remote Pro cedure Cal ls
208
209
210	4-14.1.1.
211	RPC Securi ty (“B”-Ty pe Option)
212
213
214	4-14.1.2.
215	RPCs for U se by Appl ication Pr oxy Users
216
217
218	4-14.2.
219	Request Pr ocessing
220
221
222	4-24.2.1.
223	Get an Rpc Request Ob ject: RpcR equestFact ory Class
224
225
226	4-34.2.2.
227	Set RpcReq uest Param eters: “Ex plicit” St yle
228
229
230	4-54.2.3.
231	Set RpcReq uest Param eters: “se tParams” S tyle
232
233
234	4-64.2.4.
235	Specifying Indices f or List-Ty pe RPC Par ameters
236
237
238	4-74.2.5.
239	Other Usef ul RpcRequ est Method s
240
241
242	4-84.3.
243	Response P rocessing
244
245
246	4-94.3.1.
247	RpcRespons e Class
248
249
250	4-94.3.2.
251	Request/Re sponse Exa mple
252
253
254	4-104.3.3.
255	Parsing RP C Results
256
257
258	4-104.3.4.
259	XML Respon ses
260
261
262	4-114.4.
263	How to Wri te RPCs
264
265
266	4-114.4.1.
267	Write Stat eless RPCs Whenever Possible
268
269
270	4-114.4.2.
271	When State is Needed
272
273
274	4-124.4.3.
275	Pitfalls o f Using of $JOB in S tateful RP Cs
276
277
278	4-124.4.4.
279	Pitfalls o f Global L ocking in Stateful R PCs
280
281
282	5-15.
283	VistALink Exception Reference
284
285
286	5-15.1.
287	Exception Nesting Ch anges Sinc e VistALin k 1.5
288
289
290	5-15.2.
291	VistALink Exception Hierarchy
292
293
294	5-15.2.1.
295	Common Fou ndationsEx ceptionInt erface
296
297
298	5-35.2.2.
299	VistaLinkR esourceExc eption
300
301
302	5-35.2.3.
303	Foundation sException
304
305
306	5-35.2.4.
307	VistaLinkF aultExcept ion
308
309
310	6-16.
311	Foundation s Library Utilities
312
313
314	6-16.1.
315	Encryption : gov.va.m ed.crypto
316
317
318	6-16.2.
319	J2EE Envir onment: go v.va.med.e nvironment
320
321
322	6-16.2.1.
323	Environmen t.isProduc tion()
324
325
326	6-26.2.2.
327	Environmen t.getServe rType()
328
329
330	6-26.3.
331	Network: g ov.va.med. net
332
333
334	6-26.4.
335	Audit Time r: gov.va. med.monito r.time
336
337
338	6-36.4.1.
339	Sample Cod e
340
341
342	6-46.5.
343	Exception: gov.va.me d.exceptio n
344
345
346	6-46.5.1.
347	ExceptionU tils Class
348
349
350	6-46.6.
351	XML: gov.v a.med.xml
352
353
354	6-46.6.1.
355	XmlUtiliti es Class
356
357
358	7-17.
359	How to Use VistALink in J2SE A pplication s
360
361
362	7-17.1.
363	Authentica ting and C onnecting to VistA i n Client-S erver Mode
364
365
366	7-17.1.1.
367	JAAS Overv iew
368
369
370	7-27.2.
371	VistALink JAAS Imple mentation
372
373
374	7-27.2.1.
375	VistaLogin Module
376
377
378	7-27.2.2.
379	JAAS Login Configura tion Overv iew
380
381
382	7-27.2.3.
383	VistALink- Specific J AAS Login Configurat ion
384
385
386	7-37.2.4.
387	Passing th e JAAS Log in Configu ration(s) to Your JV M
388
389
390	7-47.2.5.
391	Selecting the JAAS C onfigurati on From an Applicati on
392
393
394	7-47.2.6.
395	Selecting a VistaLog inModule C allback Ha ndler
396
397
398	7-47.2.7.
399	Benefits o f Passing Parent App lication F rame to Ca llback Han dler
400
401
402	7-57.3.
403	Putting th e Pieces T ogether: V istALink J AAS Login
404
405
406	7-57.3.1.
407	Logging in to VistA
408
409
410	7-67.4.
411	After Succ essfully L ogging In
412
413
414	7-67.4.1.
415	Retrieving the Vista KernelPrin cipal
416
417
418	7-67.4.2.
419	Retrieving the Authe nticated C onnection From the P rincipal
420
421
422	7-77.4.3.
423	Retrieving User Demo graphic In formation
424
425
426	7-87.4.4.
427	Executing RPCs
428
429
430	7-87.4.5.
431	Timeouts
432
433
434	7-87.4.6.
435	Logging Ou t
436
437
438	7-97.5.
439	Catching L ogin Excep tions
440
441
442	7-97.5.1.
443	VistaLogin Module Exc eption Hie rarchy
444
445
446	7-117.6.
447	CCOW Login Functiona lity
448
449
450	7-117.7.
451	Unit Testi ng and Vis tALink
452
453
454	1Appendix A: Pluggab le Institu tion Rules
455	Appendix A -
456
457	1Glossary
458	Glossary-
459
460
461
462	Tables and Figures
463	iiTable i. Revision History
464
465
466	3-1Table 3 ‑1. VA Ins titution M apping Rul es Example s
467
468
469	3-7Table 3 ‑2. Connec tion Speci fication C lasses
470
471
472	4-10Table 4‑1. Mappi ng RPC Ret urn Types to VistALi nk Result String For mat
473
474
475	5-2Figure 5‑1. VistA Link Excep tion Hiera rchy
476
477
478	6-4Table 6 ‑1. VistAL ink Utilit y Methods
479
480
481	6-4Table 6 ‑2. VistAL ink Utilit y Variable s
482
483
484	7-8Table 7 ‑1. Demogr aphics Key s and Valu es
485
486
487	7-10Table 7‑2. VistA Link Login Exception s
488
489
490
491
492	Orientatio n
493	XE "Orient ation"
494	This Devel oper Guide is intend ed for use in conjun ction with the VistA Link softw are. It ou tlines the details o f VistALin k-related software a nd gives g uidelines on how the software is used wi thin Healt heVet-Vete rans Healt h Informat ion System s and Tech nology Arc hitecture (VistA).
495	The intend ed audienc e of this manual is all key st akeholders . The prim ary stakeh older is t he Product Developme nt Securit y Program team. Addi tional sta keholders include:
496	HealtheVet -VistA app lication d evelopers of Web-bas ed applica tions in t he WebLogi c 9.2 and 10.x Appli cation Ser ver enviro nments.
497	Informatio n Resource Managemen t (IRM) an d Informat ion Securi ty Officer s (ISOs) a t Veterans Affairs M edical Cen ters (VAMC s) respons ible for c omputer ma nagement a nd system security.
498	Product Su pport.
499	VA facilit y personne l who will be using HealtheVet -VistA Web -based app lications running in the WebLo gic 9.2 an d 10.x App lication S erver envi ronment.
500	Document O verview
501	This manua l's intend ed audienc e includes server ad ministrato rs and IRM Informati on Technol ogy (IT) s pecialists at VA fac ilities, a s well as developers of Java a pplication s requirin g communic ation with VistA/M.
502	Generally, the insta llation an d maintena nce instru ctions pre sented her e assume t he use of Windows as the clien t operatin g system. Where appr opriate, s eparate st eps are di splayed fo r Linux.
503	Terminolog y
504	The term r esource ad apter is o ften short ened in th is guide t o "adapter ," and is also used interchang eably with the term connector.
505	Text Conve ntions
506	File names and direc tory names are set o ff from ot her text u sing bold font (e.g. , config.x ml). Bold is also us ed to indi cate GUI e lements, s uch as tab , field, a nd button names (e.g ., "press Delete").
507	All caps a re used to indicate M routine and option names (e. g., XMINET ). All cap s used ins ide angle brackets i ndicate fi le names t o be suppl ied by the user. Exa mple:
508	<JAVA_HOM E>\bin\jav a -Dlog4j. configurat ion=file:/ //c:/local Configs/my log4j.xml
509	Names for Java objec ts, method s, and var iables are indicated by Courie r font. Sn apshots of computer displays a lso appear in Courie r, surroun ded by a b order:
510	Select Ins tallation Option: LO AD a Distr ibution
511	Enter a Ho st File: X OB_1_5.KID
512	In these e xamples, t he respons e that the user ente rs at a pr ompt appea rs in bold font:
513	Enter the Device you want to p rint the I nstall mes sages.
514	You can qu eue the in stall by e nter a 'Q' at the de vice promp t.
515	Enter a '^ ' to abort the insta ll.
516	DEVICE: HO ME// <Ente r> TELNET PORT
517	Boldface t ext is als o used in code and d eployment descriptor samples t o indicate lines of particular interest, discussed in the pr eceding te xt:
518	<?xml vers ion="1.0"? >
519	<weblogic- connector xmlns="htt p://www.be a.com/ns/w eblogic/90 " xmlns:xs i=http://w ww.w3.org/ 2001/XMLSc hema-insta nce xsi:sc hemaLocati on="http:/ /www.bea.c om/ns/webl ogic/90 ht tp://www.b ea.com/ns/ weblogic/9 0/weblogic -ra.xsd">
520
521	<!-- For n ew ADAPTER -level jnd i-name, re commend us ing value of connect ion instan ce JNDI na me, append ed with Ad apter -->
522
523	<jndi-name >vlj/testc onnectorAd apter</jnd i-name>
524
525	<enable-gl obal-acces s-to-class es>true</e nable-glob al-access- to-classes >
526	The follow ing symbol s appear t hroughout the docume ntation to alert the reader to special i nformation or condit ions.
527	SymbolDesc riptionUse d to infor m the read er of gene ral inform ation and references to additi onal readi ng materia l, includi ng online informatio n. Used to caution t he reader to take sp ecial noti ce of crit ical infor mation.Add itional Re sources
528	VistALink Web Site
529	The VistAL ink websit e summariz es VistALi nk archite cture and functional ity and pr esents sta tus update s:
530	http://
		531	URL vistalink/ index.asp.
532	VistALink 1.6 Docume ntation
533	The full V istALink e nd-user do cumentatio n set cons ists of:
534	VistALink 1.6 Instal lation Gui de: Provi des detail ed instruc tions for setting up , installi ng, and co nfiguring the VistAL ink 1.6 li stener on VistA/M se rvers and the VistAL ink resour ce adapter on Java 2 Enterpris e Edition (J2EE) app lication s ervers. It s intended audience includes s erver admi nistrators , IRM IT s pecialists , and Java applicati on develop ers.
535	VistALink 1.6 System Managemen t Guide: C ontains de tailed inf ormation o n J2EE app lication s erver mana gement, in stitution mapping, t he VistALi nk adminis tration co nsole, M l istener ma nagement, and VistAL ink securi ty, loggin g, and tro ubleshooti ng.
536	VistALink 1.6 Develo per Guide (this manu al): Conta ins detail ed informa tion about workstati on setup, re-authent ication, i nstitution mapping, executing requests, VistALink exceptions , Foundati ons Librar y utilitie s, and oth er topics pertaining to writin g code tha t uses Vis tALink.
537	VistALink 1.6 Releas e Notes: L ists all n ew feature s included in each V istALink 1 .6 release .
538	VistALink 1.6 end-us er documen tation can be downlo aded from the VA Sof tware Docu ment Libra ry (VDL) W eb site at XE "VHA So ftware Doc ument Libr ary (VDL): Home Page Web Addres s"
539
540	XE "Web Pa ges:VHA So ftware Doc ument Libr ary (VDL): Home Page Web Addres s"
541
542	XE "Home P ages:VHA S oftware Do cument Lib rary (VDL) :Home Page Web Addre ss"
543
544	XE "URLs:V HA Softwar e Document Library ( VDL):Home Page Web A ddress":
545	http:// URL /vdl/appli cation.asp ?appid=163
546	VistALink 1.6 end-us er documen tation and software can be dow nloaded fr om any of the anonym ous.softwa re directo ry on the Office of Informatio n Field Of fice (OIFO ) File Tra nsfer Prot ocol (FTP) download sitesxe "E PS Anonymo us Directo ries":XE " EVS Anonym ous Direct ories":
547	Albany OIF O
548	URL
549	Hines OIFO
550	URL
551	Salt Lake City OIFO
552	URL
553	Preferred Method
554	URL
555	The docume ntation is made avai lable onli ne in Micr osoft Word format an d Adobe Ac robat Port able Docum ent Format (PDF). Th e PDF docu ments must be read u sing the A dobe Acrob at Reader (i.e., ACR OREAD.EXE) , which is freely di stributed by Adobe S ystems Inc orporated at the fol lowing Web addressXE "Adobe:Ho me Page We b Address"
556
557	XE "Web Pa ges:Adobe Home Page Web Addres s"
558
559	XE "Home P ages:Adobe Home Page Web Addre ss"
560
561	XE "URLs:A dobe Home Page Web A ddress":
562	http://www .adobe.com /
563	SSO/UC Pro ject (CCOW -Enabled L ogins)
564	VistALink implements CCOW-enab led functi onality fo r client/s erver end- user login s. For mor e informat ion on how to use Vi stALink fo r CCOW-ena bled clien t/server l ogins, see the Singl e Sign-On/ User Conte xt (SSO/UC ) document ation, on the VDL:
565	http:// URL /vdl/appli cation.asp ?appid=16 3
566	Oracle (fo rmerly kno wn as BEA) Systems
567	At the cur rent time, VistALink 1.6 has b een tested and is su pported on Oracle We bLogic Ser ver 9.2 an d 10. WebL ogic produ ct documen tation can be found at the fol lowing web site:
568	http://edo cs.bea.com /
569	DISCLAIMER : The appe arance of any extern al hyperli nk referen ces in thi s manual d oes not co nstitute e ndorsement by the De partment o f Veterans Affairs ( VA) of thi s Web site or the in formation, products, or servic es contain ed therein . The VA d oes not ex ercise any editorial control o ver the in formation you may fi nd at thes e location s. Such li nks are pr ovided and are consi stent with the state d purpose of this VA Intranet Service.In troduction
570	About this Guide
571	This docum ent is a g uide to de veloping a pplication s that uti lize VistA Link 1.6. The VistAL ink 1.6 re source ada pter is a transport layer that provides communicat ion betwee n HealtheV et Java ap plications and VistA /M servers , in both client-ser ver and n- tier envir onments. I t allows R PCs to exe cute on th e VistA/M system and return re sults to t he Java en terprise s ystem.
572	VistALink consists o f Java-sid e adapter libraries and an M-s ide listen er. The ad apter libr aries use the J2EE C onnector A rchitectur e (J2CA 1. 5) specifi cation to integrate Java appli cations wi th legacy systems. T he M liste ner proces s receives and proce sses reque sts from c lient appl ications.
573	The term r esource ad apter is o ften short ened in th is guide t o adapter, and is al so used in terchangea bly with t he term co nnector.
574	WebLogic U pdates Pro ject
575	In support of the De partment o f Veterans Affairs I nformation Technolog y applicat ion Modern ization ef fort, the three appl ications V istALink, Fat-client Kernel Au thenticati on and Aut horization (v), and Kernel Aut henticatio n and Auth orization for the Ja va 2 Enter prise Edit ion (KAAJE E) have be en develop ed. Based on the dir ection of the Techni cal Review Model (TR M) and in order to s upport app lications that upgra de to the new WebLog ic Server versions 9 .2 and 10. x, this pr oject is r equired. T he scope o f the proj ect is to upgrade th ese three applicatio ns to work with the WebLogic S erver vers ions 9.2 a nd 10.x.
576	The previo us version of VistAL ink, 1.5, was releas ed in June of 2006, and provid ed project developer s with J2E E and Java Platform, Standard Edition (J 2SE) appli cation con nectivity to VistA/M servers. It was des igned spec ifically f or J2EE 1. 3 applicat ion server s (e.g., W ebLogic 8. 1).
577	About J2EE Connector s
578	VistALink 1.6 implem ents a res ource adap ter that i s fully co mpliant wi th the J2E E Connecto r Architec ture Speci fication 1 .5. VistAL ink is acc essed prog rammatical ly through the inter faces spec ified in t he J2EE Co nnector Ar chitecture specifica tion.
579	REF: For m ore inform ation abou t J2EE Con nectors, s ee the boo k J2EE Con nector Arc hitecture and Enterp rise Appli cation Int egration, by Sharma, Stearns, and Ng (Ad dison-Wesl ey Profess ional). Al so see the J2CA 1.5 Connector Specificat ion and th e J2EE 1.4 standard. Public Vi stALink AP Is Documen tation
580	The VistAL ink 1.6 di stribution zip file supplies f ull Javado c Applicat ion Progra m Interfac e (API) re ference do cumentatio n in the / javadoc fo lder. The VistALink Javadoc de scribes th e various Java class es that ma ke up the public Vis tALink pro gramming A PI. These APIs may b e used und er the con ditions li sted in th e Javadoc documentat ion. VistA Link class es that ar e not docu mented in the VistAL ink Javado c are not part of th e supporte d VistALin k API.
581	REF: For m ore inform ation abou t the Java doc docume ntation fo rmat, plea se see
582	http://jav a.sun.com/ j2se/javad oc/.Sample Applicati ons for J2 EE Server
583	See the J2 EE Develop er Samples for examp les of how to use Vi stALink wi th a J2EE server. Th e Develope r Samples are suppli ed in the VistALink 1.6 distri bution zip file for both J2EE and J2SE m odes.
584	Deprecated VistALink APIs
585	The list o f deprecat ed APIs in VistALink 1.6 is:
586	gov.va.med .exception .Foundatio nsExceptio nInterface (and impl ementers):
587	getFullSta ckTrace() method
588	getNestedE xception() method
589	gov.va.med .exception .Foundatio nsExceptio n (and des cendants):
590	getFullSta ckTrace() method
591	getNestedE xception() method
592
593	gov.va.med .vistalink .adapter.c ci.VistaLi nkResource Exception (and desce ndants):
594	getFullSta ckTrace() method
595	getNestedE xception() method
596
597	gov.va.med .vistalink .security. VistaLogin ModuleExce ption (and descendan ts):
598	getFullSta ckTrace() method
599	getNestedE xception() method
600
601	gov.va.med .exception .Exception Utils:
602	String get FullStackT race() met hod
603	Throwable getNestedE xceptionBy Class() me thod
604	gov.va.med .xml.XmlUt ilities:
605	String con vertXmlToS tr() metho d
606	Document g etDocument ForXmlStri ng() metho d
607	Document g etDocument ForXmlInpu tStream() method
608	Attr getAt tr() metho d
609	Node getNo de() metho d
610	String XML _HEADER fi eld
611	Developer Workstatio n Setup
612	J2EE Devel opment
613	IDE
614	The follow ing librar ies should be on the project c lasspath o f your J2E E project in your in tegrated d evelopment environme nt (IDE), when devel oping modu les using VistALink J2EE conne ctors:
615	vljConnect or-1.6.0.j ar
616	vljFoundat ionsLib-1. 6.0.jar
617	A J2EE 1.4 library ( e.g., j2ee .jar, webl ogic.jar, MyEclipseI DE's j2ee library, e tc.)
618	The vlj* l ibrary jar s are prov ided in th e /app-j2e e/shared-l ib folder of the dis tribution zip file.
619	J2EE Runti me
620	At runtime , addition al librari es are req uired for your J2EE environmen t. See the VistALink 1.6 Insta llation Gu ide and th e VistALin k 1.6 Syst em Managem ent Guide for more i nformation on settin g up VistA Link conne ctors in a J2EE cont ainer.
621	J2SE Devel opment
622	IDE
623	The follow ing librar ies need t o be on th e project classpath of your J2 SE project in your I DE, when d eveloping modules us ing VistAL ink client /server co nnectivity :
624	vljConnect or-1.6.0.j ar
625	vljFoundat ionsLib-1. 6.0.jar
626	vljSecurit y-1.6.0.ja r
627	A jar cont aining J2E E 1.4 Reso urceExcept ion classe s (to meet this need ,
628	geronimo-j 2ee-connec tor_1.5_sp ec-1.0.1.j ar is prov ided in Vi stALink di stribution )
629	The vlj* l ibrary jar s and gero nimo jar a re provide d in the / samples-J2 SE folder of the Vis tALink 1.6 distribut ion file.
630	J2SE Runti me
631	At runtime , these ad ditional j ar files a re require d for your J2SE appl ication to launch an d run:
632	log4j-1.2. x.jar
633	A jar cont aining J2E E 1.4 Reso urceExcept ion classe s (to meet this need ,
634	geronimo-j 2ee-connec tor_1.5_sp ec-1.0.1.j ar is prov ided in Vi stALink di stribution )
635	These addi tional jar s can also be found in the /sa mples-J2SE folder of the VistA Link 1.6 d istributio n file.
636	How to Use VistALink in J2EE A pplication s
637	Using Stat ion Number and Divis ion
638	VistALink asks appli cation cod e to provi de VHA ins titution s tation num bers in tw o situatio ns, for di fferent pu rposes: sy stem locat ion and mu lti-divisi on awarene ss. Becaus e these tw o modes of use are s eparate, t he meaning of statio n number ( also refer red to as institutio n and divi sion) is “ overloaded .” The two modes are described in the se ctions bel ow.
639	System Loc ator: Inst itution-Co nnector Ma pping
640	Applicatio n code mus t provide a station number/div ision to r etrieve a connector JNDI name from VistA Link's ins titution-m apping API . Lacking anything b etter, sta tion numbe rs are use d as a loc ation desi gnator for a particu lar M syst em.
641	Each VistA Link conne ctor has a primarySt ation attr ibute, con figured by the J2EE administra tor. The c onfigured value shou ld exactly match the DEFAULT I NSTITUTION value in correspond ing M syst em's KERNE L SYSTEM P ARAMETERS file (#898 9.3). Vist ALink uses primarySt ation to c onfirm tha t a connec tor is acc essing the correct M system: i f the two values don 't match, connection s are reje cted.
642	The primar yStation a ttribute i s also the mapping s ource betw een statio n numbers and connec tor JNDI n ames. A VA -specific implementa tion of bu siness rul es around station nu mbers gove rns how th e institut ion mappin g API – ge tJndiConne ctorNameFo rInstituti on(divisio n) in Inst itutionMap pingDelega te – match es a reque sted divis ion with a given con nector's p rimary sta tion.
643	The mappin g API can be passed either a p rimary sta tion or a subdivisio n (a prima ry station number ap pended wit h a suffix such as ' A' or '9' (9 is a sp ecial case , represen ting a nur sing home subdivisio n). Some e xamples of how the V A rules wo rk for mat ching subd ivisions w ith primar y station numbers ar e as follo ws:
644	Division ( Institutio n Mapping API argume nt)Maps to Primary S tation6316 31631A6316 3196316396 39639A6396 399639Tabl e 3‑1. VA Institutio n Mapping Rules Exam ples
645	The primar y station for a conn ector (and for an M system) is almost al ways all-n umeric (e. g., "523") . The main exception is 200-se ries stati on numbers , which ar e only all ocated to Austin Inf ormation T echnology Center (AI TC) system s.
646	Multidivis ion-Aware Applicatio n Code: Co nnectionSp ec Credent ials
647	Applicatio n code mus t also use the stati on number to create a connecti on spec, w hich it th en uses to obtain a VistALink connection . When app lication c ode execut es a remot e procedur e call (RP C), the di vision spe cified in the connec tion spec is passed to M to po pulate the variable DUZ(2) on the M syst em. On M s ystems, se tting the proper val ue for DUZ (2) makes applicatio ns multidi vision-awa re, to giv e the righ t view of the data. On merged systems, f or example , an end-u ser might only see t he set of patients m atching th e station number spe cified in their DUZ( 2) (e.g., "523B").
648	Only one v alue can b e set into DUZ(2) at a time. S o, if you construct a connecti on spec (e .g., "conn Spec = new VistaLink VpidConnec tionSpec(d ivision, v pid)") and pass in " 523B", Vis tALink set s DUZ(2) o n the M si de to "523 B". RPCs a re then ex ecuted und er that se tting (if it is gran ted as a p ermissible subdivisi on to the end-user.) .
649	Example
650	In a merge d site, wh ere an end -user has access to "631A" but not to "6 31", the i nstitution mapping l ookup for "631A" wil l return t he connect or whose p rimaryStat ion attrib ute is "63 1". If you create a connection spec and connection to execut e an RPC a nd specify "631A", t his value will be se t into DUZ (2) on the M side. T he RPC wil l execute with multi -division awareness, i.e., tha t the curr ent instit ution is " 631A".
651	Request Cy cle
652	Using a J2 CA connect or such as VistALink in a J2EE environme nt to exec ute reques ts (RPCs) involves t he followi ng sequenc e of steps :
653	1. Retriev e a partic ular VistA Link conne ctor's con nection fa ctory from JNDI
654	2. Instant iate a Con nectionSpe c to use f or re-auth entication over the connection
655	3. Get a c onnection from the c onnection factory
656	4. Execute a request over the connection
657	5. Close t he connect ion.
658	These step s are disc ussed in m ore detail in the se ctions bel ow.
659	Retrieving the Conne ction Fact ory
660	To retriev e a connec tion facto ry from JN DI, you ne ed to know the JNDI name of th e connecti on factory . Each Vis tALink con nector goi ng to a di fferent de stination will have a differen t JNDI nam e. For thi s example, assume th at the JND I name of the connec tion facto ry is "vlj /testconne ctor."
661	To retriev e the conn ection fac tory, make the follo wing calls to JNDI:
662	String div ision="523 A"; // ord inarily ge t from KAA JEE, FatKA AT, etc.
663	Context ic = new Ini tialContex t();
664	String jnd iName = In stitutionM appingDele gate.
665	getJndiC onnectorNa meForInsti tution(div ision);
666	// cast JN DI object to VistaLi nkConnecti onFactory
667	VistaLinkC onnectionF actory cf = (VistaLi nkConnecti onFactory) ic.lookup (jndiName) ;
668	Note that the object retrieved from the JNDI must be cast to the Vista LinkConnec tionFactor y class.
669	If your ap plication hard-codes JNDI conn ection fac tory names , you may want to us e the J2EE resource- ref mechan ism to loo sely coupl e a hard-c oded JNDI name in yo ur applica tion sourc e code to an adminis trator-mod ifiable ma pping in y our applic ation depl oyment des criptors.
670	More likel y, however , in a VA environmen t, your ap plication would retr ieve JNDI connection factory n ames dynam ically, ba sed on VA facility s tation num ber. See t he “Instit ution Mapp ing” secti on later i n this cha pter, whic h describe s how to c onnect to a particul ar VA site by gettin g the JNDI name for a connecto r's connec tion facto ry.
671	Instantiat ing a Conn ection Spe c for Re-a uthenticat ion
672	Before ret rieving a connection from the connection factory o bject, you need to i nstantiate a connect ion spec. The connec tion spec is used to pass re-a uthenticat ion inform ation to t he connect ion, ident ifying the user to r un the req uest under on the ta rget VistA M system. (For a co mplete dis cussion of VistALink ’s re-auth entication mechanism , see “Mor e about Re -authentic ation
673	” below, a s well as the titled “Security ” in the V istALink S ystem Mana gement Gui de.)
674	The follow ing connec tion specs are provi ded with V istALink f or general applicati on use:
675	VistaLinkV pidConnect ionSpec(di vision, vp id)
676	VistaLinkD uzConnecti onSpec(div ision, duz )
677	VistaLinkA ppProxyCon nectionSpe c(division , appProxy Name)
678	To instant iate a Vis taLinkVpid Connection Spec, for example:
679	String vpi d = "00000 0298765432 1V65432100 0000";
680	VistaLinkV pidConnect ionSpec co nnSpec = n ew
681
682	VistaLinkV pidConnect ionSpec(di vision, vp id);
683	REF: For m ore inform ation on c onnection specs, see the secti on “Connec tion Speci fication C lasses
684	” in this document.G etting a C onnection (Connectio n Spec)
685	The follow ing code r etrieves a VistALink connectio n from a g iven conne ction fact ory:
686	VistaLinkC onnection myConnecti on = null;
687	// cast co nnection f actory get Connection to VistaL inkConnect ion
688	myConnecti on = (Vist aLinkConne ction) cf. getConnect ion(connSp ec);
689	myConnecti on.setTime Out(10000) ; // set r equest tim eout to 10 seconds
690	Every conn ection has a default timeout, which is t he time th e J2EE sid e of the c onnection waits for a response from the M system w hen execut ing an RPC . You can manually i ncrease th e timeout if you exp ect the RP Cs to take a long ti me (as in the exampl e above).
691	Executing a Request
692	Once you h ave a conn ection, yo u can exec ute a requ est over t he connect ion. In ge neral the steps to e xecute a r equest are :
693	Create an RpcRequest object
694	Set the Rp cRequest n ame of th e RPC to e xecute (Rp cRequest.s etRpcName)
695	Set the ty pe of requ est transm ission for mat to use (we recom mend propr ietary in all cases, rather th an XML)
696	Assert an RpcRequest authoriza tion conte xt (RpcReq uest.setRp cContext)
697	Set reques t paramete rs (if the request h as any)
698	Execute th e request
699	Process th e results.
700	For exampl e:
701	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
702	vReq.setRp cName("XOB V TEST PIN G");
703	vReq.setUs eProprieta ryMessageF ormat(true );
704	vReq.setRp cContext(" XOBV VISTA LINK TESTE R");
705	RpcRespons e vResp = myConnecti on.execute RPC(vReq);
706	String res ults = vRe sp.getResu lts();
707	More compl ete inform ation on s etting up a request, passing p arameters to the req uest, and processing the respo nse, is pr ovided in the “Execu ting Reque sts
708	” section.
709	Closing th e Connecti on
710	The final step in ex ecuting a request is to close the connec tion. Doin g this doe s not clos e the phys ical conne ction in J 2EE; inste ad, it ret urns the c onnection to the con nection po ol it came from, for possible re-use on a subseque nt request .
711	It is stro ngly recom mended tha t you clos e the conn ection in a final bl ock surrou nding all of the cod e, beginni ng at getC onnection( ). Otherwi se, errors will resu lt in leak ed connect ions that have not b een return ed to the pool, poss ibly causi ng the poo l to run o ut of avai lable conn ections fo r other ca llers.
712	Complete R equest Cyc le
713	The follow ing exampl e shows th e complete request c ycle, incl uding clos ing the co nnection.
714	VistaLinkC onnection myConnecti on = null;
715	String res ults = nul l;
716	String div ision="523 A"; // ord inarily ge t from KAA JEE, FatKA AT, etc.
717	String vpi d = "00000 0298765432 1V65432100 0000"; // ditto
718	try {
719
720	Context ic = new Ini tialContex t();
721	String jnd iName = In stitutionM appingDele gate.
722	getJndiCon nectorName ForInstitu tion(divis ion);
723
724	VistaLinkC onnectionF actory cf = (VistaLi nkConnecti onFactory)
725	ic.lookup( jndiName);
726	VistaLinkV pidConnect ionSpec co nnSpec = n ew
727	VistaLinkV pidConnect ionSpec(di vision, vp id);
728
729	myConnecti on = (Vist aLinkConne ction) cf. getConnect ion(connSp ec);
730
731	myConnecti on.setTime Out(10000) ; // set 1 0 second s ocket time out
732
733	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
734
735	vReq.setUs eProprieta ryMessageF ormat(true );
736
737	vReq.setRp cName("XOB V TEST PIN G");
738
739	vReq.setRp cContext(" XOBV VISTA LINK TESTE R");
740
741	RpcRespons e vResp = myConnecti on.execute RPC(vReq);
742
743	results = vResp.getR esults();
744	} catch (V istaLinkFa ultExcepti on e) {
745
746	// ...
747	} catch (N amingExcep tion e) {
748
749	// ...
750	} catch (R esourceExc eption e) {
751
752	// ...
753	} catch (F oundations Exception e) {
754
755	// ...
756	} finally {
757
758	if (myConn ection != null) {
759
760
761	try {
762
763
764
765	myConnecti on.close() ;
766
767
768	} catch (R esourceExc eption e) {
769
770
771
772	// ...
773
774
775	}
776
777	}
778	}
779	Connectivi ty Failure s and Retr y Strategi es
780	During an executeRPC ()call, co nnectivity to the Vi stA system can fail due a netw ork failur e or anyth ing else t hat breaks connectiv ity. The r equest’s i mplementat ion of the VistaLink RequestRet ryStrategy interface determine s whether VistALink automatica lly retrie s the requ est or not .
781	Connectivi ty can fai l at any p oint while executing the origi nal reques t. If it d oes, most or all of the work o f the orig inal reque st may hav e been per formed alr eady. You should tak e this int o account when consi dering wha t retry st rategy to use for yo ur request s -- for e xample, wh ether a an RPC retry could pot entially a dd a secon d instance of a part icular ent ry to a fi le.
782	By default , the impl ementation class Vis taLinkRequ estRetrySt rategyAllo w is set as the ret ry strateg y for a re quest. Its single me thod, exec ute(), ret urns “true ,” causing VistALink to attemp t to obtai n a new co nnection a nd retry t he request , exactly once.
783	In additio n to Vista LinkReques tRetryStra tegyAllow, an additi onal imple mentation class, Vis taLinkRequ estRetrySt rategyDeny , is suppl ied. Its s ingle meth od, execut e(), retur ns “false. ” You can use this c lass in ca ses where you never want the r equest to be retried .
784	You can al so supply your own i mplementat ion class for the Vi staLinkReq uestRetryS trategy in terface th at uses it s own logi c to deter mine wheth er to retu rn “true” or “false” to allow or deny th e retry at tempt.
785	For exampl e:
786	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
787	vReq.setRp cName("XOB V TEST PIN G");
788	vReq.setRp cContext(" XOBV VISTA LINK TESTE R");
789	vReq.setRe tryStrateg y(new Vist aLinkReque stRetryStr ategyDeny( ));
790	RpcRespons e vResp = myConnecti on.execute RPC(vReq);
791	String res ults = vRe sp.getResu lts();
792	More about Re-authen tication
793	Overview
794	When a con nection is used by a n applicat ion, VistA Link uses re-authent ication fo r the foll owing reas ons:
795	The connec tion proxy user used by the ad apter to c onnect to M should n ot have pr ivileges
796	Most RPCs need to ru n in the c ontext of specific e nd-users.
797	Re-authent ication is a lightwe ight secur ity contex t switch f rom the ap plication server ada pter’s use r identity to the ac tual end-u ser identi ty.
798	The archit ecture of VistALink makes the assumption that the identity o f the end- user has a lready bee n authenti cated (ver ified) by the callin g applicat ion. There fore VistA Link does not attemp t to authe nticate th e end-user ’s identit y. Instead , the re-a uthenticat ion proces s matches the end-us er identit y already establishe d by the c alling app lication w ith a matc hing VistA New Perso n file ent ry.
799	When retri eving a Vi stALink co nnection f rom a conn ection fac tory, the applicatio n supplies end-user credential s as part of the con nection sp ecificatio n. These c redentials are used to switch security c ontext on the M side , to re-au thenticate the conne ction. Thi s re-authe ntication process es tablishes the correc t end-user environme nt on the M server ( VPID, DUZ, etc) for the durati on of the connection ’s use.
800	Connection Specifica tion Class es
801	To link id entities, the applic ation sele cts one of the follo wing conne ction spec ifications to retrie ve a conne ction:
802	Connection Specifica tion class Required C redentials VistaLinkD uzConnecti onSpecDivi sion; know n DUZ valu e of a spe cific end- user (to b e deprecat ed in favo r of VPID) VistaLinkV pidConnect ionSpecDiv ision; kno wn VPID va lue of a s pecific en d-userVist aLinkAppPr oxyConnect ionSpecDiv ision; nam e of a use r of the s pecial use r type "Ap plication Proxy"Tabl e 3‑2. Con nection Sp ecificatio n Classes
803	VPID is th e connecti on specifi cation exp ected to b e used in most produ ction scen arios. Wha tever end- user authe ntication mechanism is used by a Healthe Vet-VistA applicatio n, the app lication s hould be a ble to obt ain the VP ID for a g iven end-u ser as an output fro m the auth entication process. During RPC execution , when the end-user is authent icated, th e J2EE app lication c an use the VPID as a way to id entify the end-user to any Vis tA M syste m.
804	NOTE: Kern el patch X U8.0309 is require d to suppo rt the VPI D connecti on specifi cation on M-VistA sy stems.DUZ (DuzConnec tionSpec) is the pri mary re-au thenticati on mechani sm until t he VPID in frastructu re is full y rolled o ut. At tha t point Du zConnectio nSpec will be deprec ated, and VpidConnec tionSpec w ill be the primary m echanism. In both ca ses, it is expected that the l ogin will have been performed already th rough a VH A-approved authentic ation mech anism, and that the authentica tion mecha nism will make the D UZ or VPID available for use b y the appl ication.
805	The Applic ation Prox y connecti on specifi cation is designed t o be used in cases w here the R PC should run on the Kernel/M system und er the ide ntity of a n applicat ion, rathe r than an end-user.
806	Institutio n/Division Rules for Re-authen tication
807	For every connection spec, a d ivision mu st be pass ed: the di vision par ameter is mandatory. This requ irement en sures that the divis ion reques ted for a connection on behalf of a user matches t he divisio n under wh ich the us er's reque st is exec uted on th e M system . It also helps to e nsure that RPCs are not execut ed on the wrong M sy stem.
808	All applic ations sho uld alread y be multi division-a ware, so t he VistALi nk require ment that an applica tion know the end-us er’s divis ion should be no add itional bu rden to ap plications . This val ue is set by Kernel into DUZ(2 ) for the re-authent icated end -user.
809	The value to pass fo r the divi sion param eter for a ny connect ion specif ication is the divis ion statio n number, e.g., "523 " or "523B Z". This i s the valu e found in field 99 (Station N umber) of the corres ponding en try in the Instituti on File on the M sys tem.
810	The follow ing applie s to user- based conn ection spe cs (VistaL inkVpidCon nectionSpe c and Vist aLinkDuzCo nnectionSp ec) on the M side:
811	If the end -user's DI VISION (#2 00.02) mul tiple of t heir New P erson file entry is empty, the division passed in with the c onnection spec must be the sta tion numbe r of the d ivision se t into the DEFAULT I NSTITUTION (#217) fi eld of the KERNEL SY STEM PARAM ETERS (#89 89.3) file entry for the site.
812	If an end- user has o ne or more divisions specified in the DI VISION (#2 00.02) mul tiple of t heir New P erson file entry, th e division passed in with the connection spec must be the st ation numb er for one of the di visions pr esent in t hat multip le.
813	For the Vi staLinkApp licationPr oxyConnect ionSpec, t he divisio n must be a division supported on the co mputing sy stem being connected to. In bo th cases, if the div ision pass ed does no t meet the condition s above, r e-authenti cation fai ls, and a SecurityDi visionDete rminationF aultExcept ion is ret urned to t he calling applicati on.
814	Applicatio n Proxy Us er
815	Kernel pat ch XU8.0 361 provid es the fol lowing pub lic API fo r applicat ion proxy user suppo rt:
816	CREATE(NAM E,FMAC,OPT ) ;Create an APPLICA TION PROXY user
817	For a desc ription of this API, see the K ernel Prog rammer Man ual on the Kernel AP I Web site (http:// URL /kernel/ap is/index.s html) or t he VistA D ocument Li brary (htt p:/ URL /vdl/appli cation.asp ?appid=10 ).
818	VistALink uses patch 361 funct ionality t o implemen t a new re -authentic ation conn ection spe c, VistaLi nkAppProxy Connection Spec. With this, re- authentica tion can b e performe d using an applicati on proxy a ccount on the M syst em, rather than unde r an end-u ser accoun t.
819	The Applic ation Prox y connecti on specifi cation is expected t o be used in either of the fol lowing spe cial situa tions:
820	The J2EE e nd-user do es not hav e a user a ccount on the M syst em on whic h an RPC i s to be ex ecuted – i .e., when a service uses VistA Link from an EJB (wh en an end- user is no t practica l)
821	It is not appropriat e for the RPC to exe cute under the ident ity of a p articular end-user
822	To use the Applicati on Proxy c onnection, you shoul d understa nd the fol lowing:
823	VistaLinkA ppProxyCon nectionSpe c(String d ivision, S tring appP roxyName) is the con structor f or the new connectio n spec.
824	Kernel pat ch XU836 1 supports the new f unctionali ty.
825	SecurityId entityDete rminationF aultExcept ion is thr own if re- authentica tion fails .
826	For the di vision, yo u can spec ify any di vision tha t is valid for the s ite. Divis ion checki ng is done against w hat is a v alid divis ion for th e site, no t against user-speci fic divisi on setting s.
827	If your fu nctionalit y is not m ulti-divis ional, you can use " primary st ation" for the M sys tem. This is the sta tion numbe r in the D EFAULT INS TITUTION f ield (#217 ) of the K ERNEL SYST EM PARAMET ERS file ( #8989.3) i n the M ac count in q uestion.
828
829	NOTE: Acco rding to I nfrastruct ure & Secu rity Servi ces, a val id divisio n for a Ke rnel/M sit e is curre ntly any d ivision wh ose numeri c M value (e.g., whe n “plussed ”) (1) equ als the DE FAULT INST ITUTION st ation numb er, and (2 ) is not m arked inac tive in th e Institut ion file a t the site .A "tester " applicat ion proxy user is di stributed with VistA Link, and added to t he New Per son file d uring the installati on post-in it. The pr oxy user i s named XO BVTESTER,A PPLICATION PROXY.
830	The VistAL ink sample Web appli cation dem onstrates the use of all conne ction spec s, includi ng VistaLi nkAppProxy Connection Spec. The sample app lication m akes use o f the XOBV TESTER,APP LICATION P ROXY user created du ring the V istALink i nstallatio n post-ini t.
831	The M exam ple of add ing an app lication p roxy user is shown b elow. In t his case, the proxy name is pa ssed into the functi on; no Fil eMan acces s code is added to t he user; a nd the [XO BV VISTALI NK TESTER] B-type op tion is ad ded to the secondary menu of t he proxy u ser:
832	ADDPROXY(X OBANAME)
833	; add appl ication pr oxy if not present
834	; depends on XU83 61
835	NEW XOBID
836	;
837	SET XOBID =$$CREATE^ XUSAP(XOBA NAME,"","X OBV VISTAL INK TESTER ","")
838	IF (+XOBI D)>0 DO
839	. ; actio ns if succ essfully a dded
840	IF (+XOBI D)=0 DO
841	. ; actio ns if prox y user was already p resent
842	IF (+XOBI D)<0 DO
843	. ; actio ns if erro r – could not add us er for som e reason
844	QUIT
845	J2EE Appli cation Pro xy Usage E xample
846	StringBuff er results = new Str ingBuffer( );
847	String app ProxyName = "XOBVTES TER,APPLIC ATION PROX Y";
848	String div ision="110 00"; // or dinarily g et from KA AJEE, FatK AAT, etc.
849	try {
850	VistaLin kConnectio nSpec conn Spec = new
851	VistaLinkA ppProxyCon nectionSpe c(division , appProxy Name);
852	String j ndiName = Institutio nMappingDe legate.
853	getJndiCon nectorName ForInstitu tion(divis ion);
854	Context ic = new I nitialCont ext();
855	VistaLin kConnectio nFactory c f = (Vista LinkConnec tionFactor y)
856	ic.loo kup(jndiNa me);
857	VistaLin kConnectio n myConnec tion = (Vi staLinkCon nection)
858	cf.get Connection (connSpec) ;
859	RpcReque st vReq = RpcRequest Factory.ge tRpcReques t();
860	vReq.set UseProprie taryMessag eFormat(tr ue);
861	vReq.set RpcContext ("XOBV VIS TALINK TES TER");
862	vReq.set RpcName("X OBV TEST P ING");
863	RpcRespo nse vResp = myConnec tion.execu teRPC(vReq );
864	results. append("<p >" + rpcNa me + " Res ults: <b>" +
865	vResp. getResults () + "</b> ");
866	} catch (E xception e ) {
867	// ...
868	} finally {
869	if (myCo nnection ! = null) {
870	try {
871	myCo nnection.c lose();
872	} catc h (Resourc eException e) {
873	//.. .
874	}
875	}
876	}
877	Timeouts
878	Socket-Lev el Forced Timeout
879	A simple s ocket time out capabi lity is pr ovided so that the J ava side o f the conn ection can simply ti me out the M side of the conne ction if a n RPC is t aking too long to ex ecute. If the timeou t is reach ed, the so cket will drop the c onnection to M. On t he M side, the RPC w ill termin ate ungrac efully.
880	For RPCs t hat are kn own to be long-runni ng, you ma y want to use the so cket timeo ut in conj unction wi th a grace ful RPC ti meout. Set the socke t timeout slightly l onger than you set t he gracefu l RPC-base d request- level time out. (See the “Grace ful (Reque st-Level) Timeout
881	” section below for more infor mation abo ut how to implement graceful t imeouts.)
882	Setting So cket-Level Timeouts
883	The socket -level tim eout can b e set in t wo ways:
884	On the con nection ob ject, the setTimeOut () method will set a socket ti meout, in millisecon ds, that w ill be use d for all RPCs execu ted over t he connect ion. For e xample:
885	// set tim eout for a ll request s sent ove r this con nection to 10 second s
886	myConnecti on.setTime Out(10000) ;
887	On the RPC request, the socket timeout c an be set for a sing le request :
888	// set req uest timeo ut to 10 s econds, fo r this req uest only
889	myRpcReque st.setTime Out(10000) ;
890	Default So cket-Level Timeout
891	All connec tors are c onfigured with a def ault socke t timeout, so that i f a reques t takes in finitely l ong to com plete, a s ocket time out will e ventually always be triggered.
892	Administra tors can s electively configure (tune) th e default socket tim eout for e ach connec tor, depen ding on th e WAN perf ormance an d system p erformance for reach ing any gi ven M syst em. The de fault time out is set in the go v.va.med.v istalink.c onnectorCo nfig.xml f ile. (See the sectio n “Connect or Setting s,” in the VistALink 1.6 Syste m Manageme nt Guide.)
893	Changing S ocket Time out as a M ultiple of Default T imeout
894	If you are going to programmat ically adj ust the ti meout, you may want to obtain the curren t timeout for the co nnector fi rst, multi ply it by a factor, and then s et the new timeout. This takes advantage of any tu ning the a dministrat ors may ha ve done fo r a partic ular conne ctor.
895	Example:
896	// increas e timeout by a facto r of two
897	int timeou t = myConn ection.get TimeOut();
898	myConnecti on.setTime Out(timeou t*2);
899	Graceful ( Request-Le vel) Timeo ut
900	In additio n to using a socket timeout, t he calling Java appl ication ca n also pas s a gracef ul timeout value to the RPC it is going to execute . To imple ment a gra ceful time out, the R PC code th at is exec uting must check whe ther it ha s timed ou t against this timeo ut value. A set of M APIs is p rovided fo r applicat ions to ch eck whethe r their RP C has time d out, bas ed on the value pass ed by the calling ap plication with the r equest.
901	Implementi ng a grace ful timeou t requires a delicat e synchron ization pr ocess betw een the gr aceful tim eout, the socket tim eout, and the RPC ex ecution on the M sid e. Therefo re, the gr aceful tim eout is on ly recomme nded if yo ur applica tion needs more than what the socket tim eout provi des.
902	To impleme nt a grace ful timeou t:
903	Java-side: The calli ng applica tion sets the reques t level Rp cClientTim eout prope rty, with RpcRequest .setRpcCli entTimeOut (numberOfS econds).
904	Java-side: Make sure the curre nt connect ion-level socket tim eout (in m illisecond s) evaluat es to a lo nger perio d than the graceful timeout (i n seconds) . Otherwis e the sock et may tim eout anywa y before t he gracefu l timeout is reached . For exam ple, if yo u set RpcR equest.set RpcClientT imeOut(10) , you coul d do myCon nection.se tTimeOut(1 5000), i.e ., 15 seco nds.
905	M-side RPC : The RPC code shoul d periodic ally check (e.g., if code is e xecuting a n iterativ e loop) if the RPC h as exceede d the clie nt timeout by callin g $$STOP^X OBVLIB(). Return val ues from $ $STOP^XOBV LIB are: “ 1” (applic ation shou ld stop pr ocessing, timeout ha s been exc eeded) or “0” (conti nue proces sing).
906	Java-side: The calli ng applica tion can c atch the R pcTimeOutF aultExcept ion in the try/catch code surr ounding it s RPC exec ute call. If the cal ling appli cation cat ches this exception when execu ting an RP C, it mean s the M-si de RPC che cked STOP^ XOBVLIB, w as notifie d that a t imeout had occurred, and did n ot reset t he timeout value.
907	NOTE: If t he RPC con tinues pro cessing wi thout rese tting the timeout af ter receiv ing a time out indica tor from $ $STOP^XOBV LIB, the R PC may com plete, but VistALink will retu rn an RpcT imeOutFaul tException to the cl ient.STOP^ XOBVLIB()
908	Used by th e applicat ion to det ermine if processing should st op.
909	Input vari ables: (no ne)
910	Output var iables: Re turn value . “1” is a n indicato r to stop processing ; “0” is a n indicato r to
911	continue p rocessing. I “1” is returned, and intern al “timed out” indic ator is al so set.
912
913
914	NOTE: If y ou call ST OP^XOBVLIB and it re turns 1, a fault wil l be retur ned to the calling J ava applic ation. Thi s will hap pen even i f your RPC code comp letes, unl ess you ca ll SETTO^X OBVLIB to increase t he timeout and then call STOP^ XOBVLIB to clear the "timed ou t" indicat or based o n the high er timeout value.$$G ETTO^XOBVL IB()
915	Get the cu rrent time out value (default = 300 secon ds). An ap plication would call this to o btain the current ti meout valu e.
916	Output Var iable: Re turn value , which is the timeo ut value, if it exis ts (in sec onds), or the defaul t of 300 s econds.
917	$$SETTO^XO BVLIB()
918	Override t he current "graceful " timeout setting re ceived fro m the clie nt via Rpc Request.se tRpcClient Timeout(in t) or the default.
919	It is sugg ested that you call STOP^XOBVL IB immedia tely after resetting the timeo ut value, in order t o reset th e current timeout in dicator ba sed on the new timeo ut value.
920	Input Vari able: TO. TO is the RPC timeou t value in seconds. This is al ways the t otal numbe r of secon ds since t he RPC beg an; it is not an inc rement fro m the curr ent time.
921	Output Var iable: Ret urn value. The funct ion sets t he RPC tim eout value (in secon ds) and re turns a “1 ” to indic ate value successful ly reset o r 0 if not successfu l.
922	For exampl e, if the M-side RPC wants “mo re time” a fter getti ng a “1” f rom $$STOP ^XOBVLIB, it can use the $$SET TTO call t o do so. H owever, th is is risk y, because the socke t-level ti meout may time out t he connect ion anyway , particul arly if th e calling applicatio n set the socket-lev el timeout just high er than it set the g raceful RP C timeout.
923	To add “mo re time” ( though it risks runn ing into a socket-le vel timeou t), an RPC could get the curre nt timeout value ($$ GETTO^XOBV LIB), incr ease it, a nd then re set the hi gher value with $$SE TTO^XOBVLI B. It shou ld also ca ll $$STOP^ XOBVLIB im mediately after call ing $$SETT O, in orde r to reset the "time d out" ind icator bas ed on the new value. $$STOP ne eds to be called aga in because the new $ SETTO valu e may not have been large enou gh. The ti meout chec k is alway s calculat ed from th e start of the RPC, not the re set.
924	Java and M Code RPC Timeout Ca ll Example s
925	Java-side example:
926	// increas e socket t imeout by a factor o f two and
927	// use the original socket tim eout as RP C client t imeout
928	int timeou t = myConn ection.get TimeOut();
929	myConnecti on.setTime Out(timeou t*5);
930	myConnecti on.setRpcC lientTimeO ut(timeout /1000);
931	M/VistA-si de example :
932	...
933	F S IEN=$ O(ARR(IEN) ) Q:IEN="" DO I $$ STOP^XOBVL IB() DO CL EANUP QUIT
934	. DO PROC ESS(IEN)
935	...
936	Institutio n Mapping
937	HealtheVet -VistA app lications need to be able to d ynamically retrieve connectors to variou s VistA sy stems. The connectin g systems to will ch ange over time, so h ard-coding of connec tor refere nces is ou t of the q uestion.
938	VistALink provides a n Institut ion Mappin g facility so that a dministrat ors deploy ing VistAL ink connec tors can m ap each co nnector to a specifi c VHA inst itution, u sing that institutio n's statio n number. HealtheVet -VistA app lications can then r etrieve th e JNDI nam e for a co nnector to a particu lar instit ution, usi ng the ins titution m apping fac ility. Thi s utility is in the gov.va.med .vistalink .instituti on package .
939	There is n o requirem ent to use this util ity to use VistALink . The util ity merely provides a way for administra tors to as sociate st ation numb ers with J NDI names, and for r untime cod e to retri eve the ma pping.
940	How to Con figure Map pings
941	Each conne ctor is co nfigured i n a file n amed gov.v a.med.vist alink.conn ectorConfi g.xml. Eac h connecto r's settin gs are sto red in a u nique <con nector> el ement in t hat file. The statio n number a nd JNDI na me it maps to are bo th XML att ributes of the <conn ector> ele ment.
942	Refer to t he VistALi nk 1.6 Ins tallation Guide and the VistAL ink System Managemen t Guide fo r a comple te descrip tion of ho w to confi gure VistA Link's ins titution m appings fo r each Vis tALink con nector.
943	How to Vie w the Curr ently Load ed Mapping s
944	You can vi ew the cur rently loa ded instit ution mapp ings for a given ser ver using the VistAL ink admini stration c onsole. Re fer to the VistALink 1.6 Syste m Manageme nt Guide f or a compl ete descri ption of t he VistALi nk adminis tration co nsole.
945	Retrieving Mappings for Applic ations
946	A static m ethod, get JndiConnec torNameFor Institutio n, is prov ided in th e class go v.va.med.v istalink.i nstitution .Instituti onMappingD elegate. T his class provides a pplication access to the insti tution map pings. For example:
947	String sta tionNumber = 500;
948	String jnd iConnector Name = nul l;
949	try {
950	jndiConn ectorName =
951	Instit utionMappi ngDelegate .getJndiCo nnectorNam eForInstit ution(
952	stat ionNumber) ;
953	} catch (I nstitution MappingNot FoundExcep tion e) {
954	// take so me action
955	} catch (I nstitution MapNotInit ializedExc eption e) {
956	// take so me action
957	}
958	Subdivisio ns
959	When retri eving the JNDI name for a part icular sta tion numbe r, you sho uld pass t he exact s ubdivision you are w orking wit h to the g etJndiConn ectorNameF orInstitut ion() call (e.g., "5 23A", "523 B", or "52 3"). This API determ ines the c orrect con nector ass ociated wi th a given station n umber, eve n if the s tation num ber parame ter passed to it is a subdivis ion (usual ly but not always si gnified by the prese nce of alp ha charact ers after the numeri c portion of the sta tion numbe r).
960	VistALink Java API R eference
961	For a comp lete refer ence to al l of the J ava-side V istALink i nterfaces, classes, methods an d exceptio ns, please see the J avadoc API documenta tion provi ded in the VistALink 1.6 distr ibution fi le.
962	Executing Requests
963	Remote Pro cedure Cal ls
964	A remote p rocedure c all (RPC) is a defin ed call to M code th at runs on an M serv er. Throug h the RPC Broker, a client app lication c an make a call to th e M server and execu te an RPC on the M s erver. Thi s is the m echanism t hrough whi ch a clien t applicat ion can:
965	Send data to an M se rver
966	Execute co de on an M server
967	Retrieve d ata from a n M server
968	An RPC can take opti onal param eters to d o a task a nd then re turn eithe r a single value or an array t o the clie nt applica tion.
969	REF: For d etailed in formation on RPCs, p lease refe r to Getti ng Started With the Broker Dev elopment K it (BDK) a nd/or the RPC Broker Technical Manual. Y ou can fin d both pub lications at http:// URL /vdl/ applicatio n.asp?appi d=163 . RPC Secu rity (“B”- Type Optio n)
970	All RPCs a re secured with an R PC context (a "B"-ty pe option) . The end- user on wh ose behalf an RPC is executed must have the “B”-ty pe option associated with the RPC in the ir menu tr ee. Otherw ise an exc eption is thrown.
971	REF: For m ore inform ation on R PC securit y, see Get ting Start ed with th e BDK, Cha pter 3 (Ex tract): RP C Overview , which is bundled i n the /rpc -doc folde r of the V istALink d istributio n, as the file xwb1_ 1p13dg-rpc _extract.p df.RPCs fo r Use by A pplication Proxy Use rs
972	RPCs must be explici tly marked as suppor ting execu tion by an applicati on proxy u ser, in or der to be used by on e. The new field APP PROXY ALL OWED (#.11 ) in the R EMOTE PROC EDURE file (#8994) m ust be mar ked “YES.” RPCs shou ld only be marked fo r applicat ion proxy use if:
973	The busine ss logic b ehind the RPC is val id when th e DUZ repr esents an applicatio n proxy us er (rather than end- user)
974	The applic ation expe cts to be executed b y an appli cation pro xy user.
975	Request Pr ocessing
976	During int eractions with M fro m Java, de velopers u se the Rpc Request ob ject. The RpcRequest object en capsulates the data that will be sent to M to exec ute an int eraction, i.e. the R PC name, R PC paramet ers, and R PC context . The RpcR equest obj ect is con structed u sing the R pcRequestF actory obj ect. The R PC paramet ers are ac cessed thr ough the R pcRequest objects vi a the clea rParams(), getParams () and set Params() m ethods.
977	Get an Rpc Request Ob ject: RpcR equestFact ory Class
978	The RpcReq uest class represent s a reques t from Jav a to M. As the trans port forma t, it perm its the us e of eithe r XML or a proprieta ry format. The propr ietary for mat is the default a nd is reco mmended be cause it i s faster. This class also expo ses method s for spec ifying Rpc Name, Rpc Context a nd the par ameters us ed by M to execute t he RPC.
979	The RpcReq uestFactor y class is responsib le for cre ating inst ances of R pcRequest. In order to create an RpcRequ est, the d eveloper m ust call t he static getRpcRequ est method on this c lass. In t he example shown bel ow, getRpc Request is overloade d with thr ee declara tions:
980	public sta tic RpcReq uest getRp cRequest() throws Fo undationsE xception
981	This metho d is used to create a default RpcRequest with no s pecified R pc Name or Rpc Conte xt. You mu st specify the Rpc C ontext and the Rpc N ame on the RpcReques t object b efore you can use th is object in an inte raction. R efer to ja vadoc on R pcRequest for more i nformation :
982	public sta tic RpcReq uest getRp cRequest(S tring rpcC ontext) th rows Found ationsExce ption
983	This metho d is used to create a RpcReque st with th e specifie d Rpc Cont ext. You m ust specif y the Rpc Name on th e RpcReque st object before you can use t his object in an int eraction.
984	public sta tic RpcReq uest getRp cRequest(S tring rpcC ontext, St ring rpcNa me) throws Foundatio nsExceptio n
985	Refer to t he Javadoc s on RpcRe quest for more infor mation.
986	This metho d is used to create a RpcReque st with th e specifie d Rpc Cont ext and th e Rpc Name . You may still spec ify anothe r Rpc Cont ext and Rp c Name on this objec t. Refer t o the Java Docs on Rp cRequest f or more in formation.
987	getRpcRequ est() Exam ple
988	RpcRequest vReq = nu ll;
989	//The Rpc Context
990	String rpc Context = "XOBV VIST ALINK TEST ER";
991	//The Rpc to call
992	String rpc Name = "XW B GET VARI ABLE VALUE ";
993	// Constru ct the req uest objec t
994	try{
995	vReq = R pcRequestF actory.get RpcRequest (rpcContex t, rpcName );
996	} catch(Fo undationsE xception e ) {
997
998	// process exception as needed
999	}
1000	Set RpcReq uest Param eters: “Ex plicit” St yle
1001	There are two ways o f passing RPC parame ters to an RpcReques t object. For conven ience, the first met hod is ref erred to a s “explici t” style, the second method as “setParam s” style.
1002	In explici t style, t he method of passing RPC param eters corr esponds ve ry closely to the un derlying R PC paramet ers. The R PC Broker has three input para meter type s for RPC calls. The se map to VistALink RpcRequest Param para meter type s as follo ws:
1003	RPC parame ter typeVi stALink Rp cRequestPa ram typeJa va value t ypeLiteral "string"St ringRefere nce"ref"St ringList"a rray"List (Specify a rray indic es yoursel f; support s non-inte ger, negat ive, or mu lti-level indices)
1004	Map or Set (index a utomatical ly generat ed as a si ngle-level , integer, sequence) To pass pa rameters i nto an Rpc Request, y ou should retrieve t he RpcRequ est's muta ble RpcReq uestParam object, ac cessible b y RpcReque st.getPara ms(). Then , call set Param() on that obje ct to defi ne each RP C paramete r:
1005	void setPa ram(int po sition, St ring type, Object va lue)
1006	The parame ters to th is call ar e:
1007	position: the expect ed RPC par ameter lis t position where the RPC expec ts to see the RPC pa rameter
1008	type: can be "string ", "ref" o r "array" (to match the expect ed RPC par ameter typ e)
1009	value: an object tha t is the v alue of th e RPC para meter. For "string" or "ref" t ypes, the object sho uld be a s tring. For "array" t ypes, the object sho uld implem ent the Ma p, List or Set inter face.
1010	Literal RP C Paramete r Example
1011	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1012	vReq.getPa rams().set Param(1, " string", " I am a str ing");
1013	Reference RPC Parame ter Exampl e
1014	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1015	vReq.getPa rams().set Param(1, " ref", "DTI ME");
1016	List RPC P arameter E xample:
1017	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1018	ArrayList nums = new ArrayList ();
1019	nums.add(" 3");
1020	nums.add(" 5");
1021	nums.add(" 4");
1022	nums.add(" 1");
1023	nums.add(" 7");
1024	nums.add(" 8");
1025	nums.add(" 2");
1026	nums.add(" 6");
1027	nums.add(" 9");
1028	vReq.getPa rams().set Param(1, " array", nu ms);
1029	Combinatio n RPC Para meter Exam ple:
1030	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1031	ArrayList nums = new ArrayList ();
1032	nums.add(" 3");
1033	nums.add(" 5");
1034	nums.add(" 4");
1035	nums.add(" 1");
1036	nums.add(" 7");
1037	nums.add(" 8");
1038	nums.add(" 2");
1039	nums.add(" 6");
1040	nums.add(" 9");
1041	vReq.getPa rams().set Param(1, " array", nu ms);
1042	vReq.getPa rams().set Param(2, " string", " I am a str ing");
1043	vReq.getPa rams().set Param(3, " ref", "DTI ME");
1044	Set RpcReq uest Param eters: “se tParams” S tyle
1045	A second s tyle of pa ssing RPC parameters for an RP C into an RpcRequest object is called th e “setPara ms” style. This meth od offers a small am ount of ab straction from the u nderlying RPC, altho ugh parame ters still must corr espond dir ectly to w hat is exp ected by t he RPC bei ng invoked .
1046	With the s etParams s tyle, you create an object tha t implemen ts the Lis t interfac e and hold s each of the parame ters as an object en try in the list. Add each para meter to t he List as an object value, an d then use RpcReques t.setParam s(List) to pass the RPC parame ters to th e request. .
1047	The RpcReq uest objec t processe s the List internall y extracti ng the RPC parameter character istics for the reque st as foll ows:
1048	position: Determined by the or der each o bject was added to t he List. T he first o bject adde d becomes the first RPC parame ter, the s econd beco mes the se cond, and so forth.
1049	type:
1050	If an obje ct found i n the List is a Stri ng, it is passed as an RPC lit eral param eter.
1051	If an obje ct found i n the List implement s the Map, List, or Set interf aces, it i s passed a s an RPC L ist parame ter.
1052	If an obje ct found i n the List is an ins tance of t he special RpcRefere nceType cl ass, it is passed as an RPC re ference pa rameter.
1053	value: The value for the RPC p arameter i s simply t he object added to t he List fo r each par ameter.
1054	Literal RP C Paramete r Example:
1055	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1056	ArrayList params = n ew ArrayLi st();
1057	params.add ("I am a s tring");
1058	vReq.setPa rams(param s);
1059	Reference RPC Parame ter Exampl e:
1060	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1061	ArrayList params = n ew ArrayLi st();
1062	params.add (new RpcRe ferenceTyp e("DTIME") );
1063	vReq.setPa rams(param s);
1064	List RPC P arameter E xample:
1065	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1066	ArrayList params = n ew ArrayLi st();
1067	ArrayList nums = new ArrayList ();
1068	nums.add(" 3");
1069	nums.add(" 5");
1070	nums.add(" 4");
1071	nums.add(" 1");
1072	nums.add(" 7");
1073	nums.add(" 8");
1074	nums.add(" 2");
1075	nums.add(" 6");
1076	nums.add(" 9");
1077	params.add (nums);
1078	vReq.setPa rams(param s);
1079	Combinatio n RPC Para meter Exam ple:
1080	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1081	ArrayList params = n ew ArrayLi st();
1082	ArrayList nums = new ArrayList ();
1083	nums.add(" 3");
1084	nums.add(" 5");
1085	nums.add(" 4");
1086	nums.add(" 1");
1087	nums.add(" 7");
1088	nums.add(" 8");
1089	nums.add(" 2");
1090	nums.add(" 6");
1091	nums.add(" 9");
1092	params.add (nums);
1093	params.add ("I am a s tring");
1094	params.add (new RpcRe ferenceTyp e("DTIME") );
1095	vReq.setPa rams(param s);
1096	Specifying Indices f or List-Ty pe RPC Par ameters
1097	List-type RPC parame ter values can be pa ssed to Vi stALink in Java obje cts that i mplement t he List, S et, or Map interface s.
1098	If you pas s List-typ e paramete r values i n an objec t that imp lements Li st or Set (but not M ap), the a rray index is automa tically ge nerated fo r you, as a single-l evel, inte ger, seque ntial inde x starting at “1.” ( The array becomes th e array su bscript le vel in M f or the dat a.) This c an be conv enient if the array index is n ot signifi cant for y our RPC.
1099	However, i f you need any of th e followin g features in your a rray when it is pass ed to M, u se an obje ct that im plements M ap (such a s HashMap) instead:
1100	Negative i ndex value s
1101	Non-sequen tial index values
1102	Control ov er the ind ex start p oint
1103	Non-intege r index va lues
1104	Multi-leve l indices (>1 subscr ipt level in M)
1105	For each e ntry added to the Ma p object, the key be comes the M subscrip t, and the value bec omes the M value.
1106	To pass a multi-leve l subscrip t, use the RpcReques t.buildMul tipleMSubs criptKey() method to generated the HashM ap key.
1107	List RPC P arameter E xample (Ex plicit Ind ex)
1108	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1109	ArrayList params = n ew ArrayLi st();
1110	HashMap hm = new Has hMap();
1111	hm.add(".1 1", "0");
1112	hm.add("12 02", "23") ;
1113	hm.add("12 05", "595" );
1114	hm.add("ti me", "NOW" );
1115	params.add (hm);
1116	vReq.setPa rams(param s);
1117	List RPC P arameter E xample (Ex plicit Mul ti-Level I ndex)
1118	RpcRequest vReq = Rp cRequestFa ctory.getR pcRequest( );
1119	ArrayList params = n ew ArrayLi st();
1120	HashMap hm = new Has hMap();
1121	hm.put(Rpc Request.bu ildMultipl eMSubscrip tKey("\"FR UIT\",1"), "Apple");
1122	hm.put(Rpc Request.bu ildMultipl eMSubscrip tKey("\"FR UIT\",2"), "Orange") ;
1123	hm.put(Rpc Request.bu ildMultipl eMSubscrip tKey("\"FR UIT\",3"), "Pear");
1124	hm.put(Rpc Request.bu ildMultipl eMSubscrip tKey("\"FR UIT\",4"), "'nana");
1125	params.add (hm);
1126	vReq.setPa rams(param s);
1127	Other Usef ul RpcRequ est Method s
1128	For a comp lete list of other a vailable R pcRequest methods, p lease see the Javado c for RpcR equest.
1129	Clear Prev ious Reque st Paramet ers
1130	If you are re-using a request object for additiona l requests , the RpcR equest.cle arParams m ethod is p rovided so that you can clear any existi ng paramet ers. You s hould call this meth od before attempting to set RP C paramete rs for sub sequent re quests:
1131	//clear th e params
1132
1133	vReq.clear Params();
1134	Set the Me ssage Form at (Propri etary or X ML)
1135	VistALink' s XML mess age format is based on the XML standard. As the tr ansport fo rmat, it p ermits the use of ei ther XML o r a propri etary form at. RpcReq uest defau lts to the proprieta ry format because it is faster .
1136	//Set the request to use the p ropietary message fo rmat
1137	vReq.setUs eProprieta ryMessageF ormat(true );
1138	//Set the request to use the X ML message format
1139	vReq.setUs eProprieta ryMessageF ormat(fals e);
1140	Set the RP C Context
1141	If you are re-using a request object for additiona l requests , you can change the RPC Conte xt with th is method:
1142	private st atic final String RP CCONTEXT = "XOBV VIS TALINK TES TER";
1143	vReq.setRp cContext(R PCCONTEXT) ;
1144	Set the RP C Name
1145	If you are re-using a request object for additiona l requests , you can change the RPC Name with this method:
1146	vReq.setRp cName("XOB V TEST NOT IN CONTEX T");
1147	Set the RP C Client T imeout
1148	This metho d sets a “ graceful” timeout pe riod that is made av ailable to the RPC c ode on the M system. It is up to the M c ode to hon or the tim eout perio d, however . The valu e sent def aults to 6 00 seconds . You can change thi s value by calling t he setRpcC lientTimeO ut method:
1149	private st atic final int TIMEO UT = 300;
1150	vReq.setRp cClientTim eOut(TIMEO UT);
1151	REF: For m ore inform ation on t he differe nt kinds o f timeouts , see the "Timeouts
1152	" section. Response P rocessing
1153	Once you h ave set up RpcReques t, you can execute a n RPC inte raction on the VistA LinkConnec tion objec t, using t he RpcRequ est object . Doing th is returns an RpcRes ponse obje ct. RpcRes ponse is a value obj ect that p rovides in formation about the response r eturned fr om M.
1154	RpcRespons e Class
1155	The RpcRes ponse clas s is a val ue object that provi des inform ation abou t the resp onse retur ned from M . The RpcR esponse ob ject expos es methods to retrie ve the res ults, resu lts type, and an org .w3c.dom.d ocument ob ject that contains t he results , if the r esults are in XML fo rmat.
1156	Request/Re sponse Exa mple
1157	//request and respo nse object s
1158	RpcRequest vReq = nu ll;
1159	RpcRespons e vResp = null;
1160	//The Rpc Context
1161	String rpc Context = "XOBV VIST ALINK TEST ER";
1162	//The Rpc to call
1163	String rpc Name = "XO BV TEST ST RING";
1164	//Construc t the requ est object
1165	try {
1166	vReq = R pcRequestF actory.get RpcRequest (rpcContex t, rpcName );
1167	} catch(Fo undationsE xception e ) {
1168	// proce ss excepti on as need ed
1169	}
1170	//clear th e params
1171
1172	vReq.clear Params();
1173	//Set the params
1174	vReq.getPa rams(). se tParam(1, "string", "This is a test stri ng!");
1175	//Set the request to use the p roprietary message f ormat
1176	vReq.setUs eProprieta ryMessageF ormat(true );
1177	//Execute the Rpc an d construc t the resp onse with the
1178	//RpcRespo nseFactory
1179	try {
1180	vResp = vistaLinkC onnection. executeRPC (vReq);
1181	} catch(Vi staLinkFau ltExceptio n e) {
1182	// proce ss excepti on as need ed
1183	} catch(Fo undationsE xception e ) {
1184	// proce ss excepti on as need ed
1185	}
1186	//Display the respo nse
1187	System.out .println(v Resp.getRe sults());
1188	Parsing RP C Results
1189	All result s from RPC s are retu rned as a single str ing from R pcResponse .getResult s().
1190	The RPC Br oker defin es five re turn types for RPCs (at the ti me of the current Vi stALink re lease). Th e mapping between th ese return types and the singl e string r eturned th rough Vist ALink are as follows :
1191	RPC Return TypeVistA Link Resul t String F ormatSingl e ValueAs- isGlobal I nstanceAs- isArrayAll array nod es concate nated sequ entially, with each delimited by linefee d (ASCII 1 0) charact erGlobal A rrayAll ar ray nodes concatenat ed sequent ially, wit h each del imited by linefeed ( ASCII 10) characterW ord Proces singEach w ord proces sing "line " concaten ated seque ntially, s eparated b y a linefe ed (ASCII 10) charac terTable 4 ‑1. Mappin g RPC Retu rn Types t o VistALin k Result S tring Form at
1192	One easy w ay to pars e array-ty pe results concatena ted with l ine feeds is with th e Java str ing tokeni zer. For e xample:
1193	StringToke nizer st = new Strin gTokenizer (vResp.get Results(), "\n");
1194	int cnt = st.countTo kens();
1195	for (int i = 0; i < cnt; i++) {
1196
1197	system.out .println(" Result nod e " + i + ": " + st. nextToken( ));
1198	}
1199	In JDK 1.5 and forwa rd, Sun de precates S tringToken izer in fa vor of the split() f unction in java.lang .String.XM L Response s
1200	Some newer RPCs may choose to return the ir results as an XML document. The RpcRe sponse cla ss provide s two help er methods to turn t he normal results st ring into an XML doc ument. If you expect the resul ts from an RPC to be an XML do cument, yo u can call RpcRespon se.isXmlRe sponse to confirm if the respo nse is in XML format , and RpcR esponse.ge tResultsDo cument to convert th e result s tring into an XML do cument:
1201	//Get a or g.w3c.dom. document o bject that contains the result s if set
1202	if (vReq.i sXmlRespon se()) {
1203	org.w3c.do m.document xmlDoc = null;
1204	try{
1205	xmlDoc = v Resp.getRe sultsDocum ent());
1206	}catch(Rpc ResponseTy peIsNotXml Exception e){
1207	// process exception as needed
1208	}catch(Fou ndationsEx ception e) {
1209	// process exception as needed
1210	}
1211	}
1212	How to Wri te RPCs
1213	For guidel ines on ho w to write RPC Broke r RPCs, pl ease refer to the ex tract Gett ing Starte d With The BDK Chapt er 3 (Extr act): RPC Overview f rom the RP C Broker m anual, bun dled in th e /rpc-doc folder of the VistA Link distr ibution. S ome specia l consider ations app ly to writ ing RPCs i n the new modes supp orted by V istALink, including n-tier. Th ese are di scussed in the secti ons below.
1214	Write Stat eless RPCs Whenever Possible
1215	When writi ng new RPC s to execu te in an n -tier envi ronment, w e recommen d making t hem statel ess whenev er possibl e. “Statel ess” means that each RPC execu tion is st andalone: when a seq uence of R PCs is exe cuted, the re is no s tate maint ained on t he M syste m between RPC execut ions. This way, if y ou need to use an RP C from one sequence of RPCs in another s equence, y our code w ill be mor e flexible .
1216	The two ma in M-side state mech anisms tra ditionally used in R PCs -- $J (as a temp orary stor age index) and globa l locking -- are bot h problema tic in an n-tier env ironment. In the n-t ier model, there is no guarant ee that yo ur request s will exe cute in th e same M j ob partiti on. Middle -tier code will be r etrieving and return ing VistAL ink connec tions to a connectio n pool acr oss a numb er of clie nt-tier ac cesses, an d because connection s are not “dedicated ” to a sin gle user s ession, th e underlyi ng M parti tion may b e a differ ent one ea ch time, w ith a diff erent $J.
1217	When State is Needed
1218	When you d o need to maintain s tate on th e M system between R PC invocat ions, the two approa ches discu ssed in th e sections below are recommend ed. They a re more co mpatible w ith the n- tier model .
1219	Session ID as Tempor ary Storag e Index
1220	Rather tha n using $J for a tem porary sto rage index , we recom mend that you implem ent a sess ion ID, gu aranteed t o be uniqu e on the M system, t o index st orage on t he M syste m, and tha t you main tain the s ession ID state on t he middle tier. You can then u se the ses sion ID be tween midd le-tier in vocations on a varie ty of conn ections wi th differe nt underly ing $Js an d still be able to c onsistentl y retrieve your inde xed tempor ary data f rom the M system.
1221	NOTE: Kern el may pro vide a new API for m iddle tier s to obtai n a guaran teed uniqu e M system session i dentifier to index t emporary s torage loc ations.Fil eMan-Based Lock File
1222	An alterna tive to th e M LOCK c ommand is to impleme nt a FileM an-based l ock file m echanism t o synchron ize lockin g across r equests, c onnections , and midd le-tier ac cesses. No te that a lock file needs to b e used in all applic ation code that need s to honor the lock – whether “roll & sc roll,” cli ent-server , or n-tie r.
1223	You will p robably al so need AP Is for loc king and u nlocking. Locks shou ld probabl y be unloc ked automa tically af ter a peri od of time (e.g., lo st connect ion) or ba sed on som e state ch ange or ev ent in the applicati on session .
1224	Pitfalls o f Using of $JOB in S tateful RP Cs
1225	When runni ng RPCs in an n-tier model, th ere is no guarantee that all y our reques ts will ex ecute in t he same M job partit ion. Your middle tie r will be retrieving and retur ning VistA Link conne ctions to a connecti on pool ac ross clien t-tier acc esses, and each conn ection ret rieved fro m the conn ection poo l may have a differe nt $J.
1226	If you hav e an RPC s equence th at shares data acros s RPCs usi ng tempora ry M stora ge indexed by $J, th e RPC sequ ence must be perform ed over th e same con nection (o r else $J will chang e). In n-t ier mode, this means the RPC s equence mu st be exec uted over one connec tion befor e closing it (return ing it to the connec tion pool) .
1227	Another $J -related i ssue can o ccur even if you exe cute an RP C sequence over a si ngle conne ction. The default V istaLinkRe questRetry Strategy i mplementat ion allows a request to be ret ried. If y ou use it and connec tivity fai ls, the re quest will be retrie d on a new connectio n, and the refore usi ng a new $ J. So if y our RPCs c ommunicate by leavin g values o n the M sy stem index ed by $J, you should consider using Vist aLinkReque stRetryStr ategyDeny for those requests.
1228	Pitfalls o f Global L ocking in Stateful R PCs
1229	When runni ng RPCs in an n-tier model, lo cking glob al nodes a cross RPCs presents the same i ssues as w hen using $J across RPCs. In p articular, you canno t lock dat a in an RP C over one connectio n and unlo ck data in a differe nt connect ion. Also, if the M partition that sets a lock exi ts, the M operating system aut omatically clears th e lock. Th erefore lo cking can only be us ed safely within a s ingle RPC, or within an RPC se quence tha t will be executed o ver a sing le connect ion.
1230	As with $J , another locking-re lated issu e can occu r if netwo rk connect ivity fail s and your request i s retried (which wou ld be over a differe nt connect ion). Ther efore you should con sider usin g VistaLin kRequestRe tryStrateg yDeny for requests t hat depend on lockin g across R PCs: if co nnectivity fails and a request is retrie d, the req uest will be retried over a ne w connecti on that do es not own the lock. (The lock may be re leased any way, since the previ ous partit ion will p robably ex it as a co nsequence of the net work conne ctivity fa ilure).
1231	VistALink Exception Reference
1232	VistALink, like any other Java applicati on, uses e xceptions to indicat e various error cond itions tha t can occu r during e xecution. VistALink throws onl y checked exceptions .
1233	Exception Nesting Ch anges Sinc e VistALin k 1.5
1234	Previous v ersions of VistALink were desi gned to wo rk with Ja va version 1.3, whic h did not support ne sted excep tions. As a result, nested exc eption cap ability wa s built in to all Vis tALink exc eption cla sses. Now that Java version 1. 4 and abov e support nested exc eptions "o ut of the box", Vist aLink's ne sted excep tion facil ities are deprecated , the clas ses themse lves have been inter nally redi rected to store nest ed excepti ons using Java's nes ted except ion functi onality in stead.
1235	Any code t hat is usi ng VistALi nk's depre cated nest ed excepti on facilit ies should switch to the stand ard Java n ested exce ption faci lities. In particula r:
1236	Any code u sing the g etNestedEx ception() method of any VistAL ink-provid ed excepti on (define d, and now deprecate d, in Foun dationsExc eptionInte rface) sho uld switch to the JR E-provided Throwable .getCause( ) method i nstead.
1237	Any code u sing the g etFullStac kTrace() m ethod of a ny VistALi nk-provide d exceptio n should s witch to t he JRE-pro vided Thro wable.getS tackTrace( ) instead.
1238	VistALink Exception Hierarchy
1239	VistALink security m odules and the VistA Link resou rce adapte r modules often thro w more exc eptions mo re specifi c than wha t is decla red to be thrown.
1240	Because Vi stALink im plements v arious Jav a specific ations (e. g., Java A uthenticat ion and Au thorizatio n Service (JAAS) and J2EE Conn ectors), e ach Java s pecificati on dictate s usage of a specifi c base exc eption cla ss. To be able to wo rk with al l types of exception s, VistALi nk also de fines one unifying e xception i nterface: gov.va.med .exception .Foundatio nsExceptio nInterface .
1241	For exampl e, where t he JAAS sp ecificatio n requires a LoginEx ception to be thrown , methods in the Vis taLinkLogi nModule ma y throw Vi staLoginMo duleExcept ion (which subclasse s LoginExc eption and implement s Foundati onsExcepti onInterfac e) or an e ven more s pecific ex ception li ke VistaLo ginModuleN oJobSlotsA vailableEx ception.
1242	Common Fou ndationsEx ceptionInt erface
1243	gov.va.med .exception .Foundatio nsExceptio nInterface is define d to be ab le to have common in terface fo r all type s of VistA Link excep tions. Imp lementatio n of this interface allows gov .va.med.ex ception.Ex ceptionUti ls to work exception s, no matt er what th ey inherit from.
1244	Foundation sException Interface
1245	│
1246	├ Founda tionsExcep tion (exte nds java.l ang.Except ion)
1247	│
1248	│
1249	│
1250	├ Institut ionMapNotI nitialized Exception
1251	│
1252	├ Institut ionMapping NotFoundEx ception
1253	│
1254	├ RpcRespo nseTypeIsN otXmlExcep tion
1255	│
1256	├ VistaKer nelHashCou ntLimitExc eededExcep tion
1257	│
1258	│
1259	│
1260	├ VistaLin kFaultExce ption
1261	│
1262	│ │
1263	│
1264	│ ├ Login sDisabledF aultExcept ion
1265	│
1266	│ ├ NoJob SlotsAvail ableFaultE xception
1267	│
1268	│ ├ RpcFa ultExcepti on
1269	│
1270	│ │ ├ No RpcContext FaultExcep tion
1271	│
1272	│ │ ├ Rp cNotInCont extFaultEx ception
1273	│
1274	│ │ └ Rp cTimeOutFa ultExcepti on
1275	│
1276	│ │ └ Rp cNotOkForP roxyUseExc eption
1277	│
1278	│ │
1279	│
1280	│ └ Secur ityFaultEx ception
1281	│
1282	│ ├ Se curityAcce ssVerifyCo dePairInva lidExcepti on
1283	│
1284	│ ├ Se curityConn ectionProx yException
1285	│
1286	│ ├ Se curityDivi sionDeterm inationFau ltExceptio n
1287	│
1288	│ ├ Se curityIden tityDeterm inationFau ltExceptio n
1289	│
1290	│ ├ Se curityIPLo ckedFaultE xception
1291	│
1292	│ ├ Se curityPrim aryStation MismatchEx ception
1293	│
1294	│ ├ Se curityProd uctionMism atchExcept ion
1295	│
1296	│ ├ Se curityTooM anyInvalid LoginAttem ptsFaultEx ception
1297	│
1298	│ ├ Se curityUser Authorizat ionExcepti on
1299	│
1300	│ └ Se curityUser VerifyCode Exception
1301	│
1302	│
1303	│
1304	└ VistaSoc ketExcepti on
1305	│
1306	│
1307	│
1308	├ Vista LinkSocket AlreadyClo sedExcepti on
1309	│
1310	└ Vista SocketTime OutExcepti on
1311	│
1312	├ VistaL inkResourc eException (extends
1313	│
1314	│ java x.resource .ResourceE xception)
1315	│
1316	├ Connecti onHandlesE xceededExc eption
1317	│
1318	├ HeartBea tFailedExc eption
1319	│
1320	│ └ Heart BeatInitia lizationFa iledExcept ion
1321	│
1322	└ VistaLin kSocketClo sedExcepti on
1323	│
1324	└ VistaL oginModule Exception (extends
1325
1326	│ javax .security. auth.login .LoginExce ption)
1327
1328	├ VistaLog inModuleIP LockedExce ption
1329
1330	├ VistaLog inModuleLo ginsDisabl edExceptio n
1331
1332	├ VistaLog inModuleNo JobSlotsAv ailableExc eption
1333
1334	├ VistaLog inModuleNo PathToList enerExcept ion
1335
1336	├ VistaLog inModuleTo oManyInval idAttempts Exception
1337
1338	├ VistaLog inModuleUs erCancelle dException
1339
1340	└ VistaLog inModuleUs erTimedOut Exception
1341	Figure 5‑1 . VistALin k Exceptio n Hierarch y
1342	VistaLinkR esourceExc eption
1343	J2EE Conne ctors requ ires adapt er methods to throw javax.reso urce.Resou rceExcepti on.
1344	VistALink implements gov.va.me d.vistalin k.adapter. cci.VistaL inkResourc eException that exte nds javax. resource.R esourceExc eption. Vi staLinkRes ourceExcep tion is th rown from all J2EE C onnectors required m ethods as well as an y custom m ethod in V istALink t hat implem ents conne ction mana gement int erfaces.
1345	VistaLinkR esourceExc eption mor e specific exception subclasse s include (see Figur e 5‑1. Vis tALink Exc eption Hie rarchy
1346	):
1347	Connection HandlesExc eededExcep tion
1348	VistaLinkS ocketClose dException
1349	HeartBeatF ailedExcep tion
1350	HeartBeatI nteraction FailedExce ption.
1351	Foundation sException
1352	The J2EE C onnector A rchitectur e specific ation defi nes option al record and intera ction mana gement int erfaces th at are not implement ed in Vist ALink. Ins tead, Vist ALink uses VistaLink Connection ::executeR PC(), Vist aLinkConne ction::exe cuteIntera tion() and classes i n gov.va.m ed.vistali nk.adapter .record pa ckage to i mplement i nteraction and recor d manageme nt. These methods ar e not gove rned by th e J2EE Con nector Arc hitecture specificat ion. Hence VistALink uses gov. va.med.exc eption.Fou ndationsEx ception an d its subc lasses in these meth ods.
1353	VistaLinkF aultExcept ion
1354	VistALink communicat ions with M can prod uce except ions that originate from the J ava code s ide. In th at case, V istaLinkRe sourceExce ption and Foundation sException will be t hrown (des cribed abo ve).
1355	VistALink communicat ions with M can also produce e xceptions that origi nate from the M side . In those cases a F ault messa ge is sent back to V istALink f rom M. Fau lt message s are pars ed and gov .va.med.vi stalink.ad apter.reco rd.VistaLi nkFaultExc eption tha t extends Foundation sException are const ructed to be thrown in those c ases.
1356	VistaLinkF aultExcept ion will h ave all th e informat ion that i s sent bac k from the M side to Java, inc luding: fa ultCode, f aultString , faultAct or, errorC ode, error Type and e rrorMessag e.
1357	VistaLinkF aultExcept ion more s pecific ex ception su bclasses i nclude (se e Figure 5 ‑1. VistAL ink Except ion Hierar chy):
1358	NoJobSlots AvailableF aultExcept ion
1359	LoginsDisa bledFaultE xception
1360	SecurityFa ultExcepti on (contai n more spe cific subc lasses)
1361	RpcFaultEx ception (c ontain mor e specific subclasse s)
1362	Foundation s Library Utilities
1363	The Java A PIs discus sed in thi s chapter are the Fo undations Library ut ilities. T hey are pr ovided in vljFoundat ionsLib-1. 6.0.jar.
1364	Encryption : gov.va.m ed.crypto
1365	The VistaK ernelHash utility cl ass implem ents a two -way hash via two st atic metho ds, encryp t and decr ypt. These provide t he encodin g and obfu scation al gorithms u sed by the RPC Broke r and Kern el to enco de and dec ode data s trings.
1366	Using thes e algorith ms makes i t harder t o sniff th e contents of text s ent over t he network . This is not, howev er, encryp tion-class encoding, nor does it protect against r eplay atta cks of un- decoded st rings. As a two-way hash, this algorithm should no t be consi dered an i mplication or achiev ement of a ny particu lar securi ty level b eyond obfu scation.
1367	Example (e ncoding):
1368	String enc odedString =
1369	VistaKer nelHash.en crypt("som e text to encode", t rue);
1370	The second parameter is useful if the te xt is to b e passed i n a CDATA section of an XML me ssage. If this param eter is se t to true, the retur ned encode d strings will conta in neither "]]>" nor "<![CDATA [". Otherw ise, it is possible a returned encoding may contai n those ch aracter se quences. I f, in a re asonable n umber of t ries, an e ncoded str ing cannot be create d without these CDAT A boundari es, an exc eption is thrown of type Vista KernelHash CountLimit ExceededEx ception.
1371	Example (d ecoding):
1372	String dec odedString =
1373	VistaKer nelHash.de crypt(enco dedString) ;
1374	J2EE Envir onment: go v.va.med.e nvironment
1375	Environmen t.isProduc tion()
1376	Returns wh ether or n ot the adm inistrator has confi gured the J2EE serve r to be "p roduction" in a VA-m edical-cen ter sense, i.e., the system is operating on produc tion VA da ta. The so urce of th e setting is the gov .va.med.en vironment. production JVM argum ent passed to the J2 EE server upon start up. A sett ing of “tr ue” design ates the s erver as a productio n server; any other value (inc luding not passing t he JVM arg ument at a ll) marks the server as a non- VA product ion server .
1377	Returns: t rue if the server is a VA prod uction ser ver, false if not.
1378	Environmen t.getServe rType()
1379	Returns th e J2EE ser ver type. The source of the se tting is t he gov.va. med.enviro nment.serv ertype JVM argument passed to the J2EE s erver upon startup. If the JVM argument is not pre sent, auto -detects f or WebLogi c only, an d otherwi se default s to retur n UNKNOWN if auto-de tection fa ils.
1380	Returns: S erverType: JBOSS \| O RACLE \| SU N_RI_13 \| UNKNOWN \| WEBLOGIC \| WEBSPHERE \| TOMCAT \| J2SE
1381	Example:
1382	if (Enviro nment.getS erverType( ).equals(S erverType. WEBLOGIC)) {
1383	// exec ute weblog ic-specifi c code
1384	}
1385	Network: g ov.va.med. net
1386	The follow ing classe s provide basic sock et-based n etwork fun ctionality :
1387	SocketMana ger: Repre sents a so cket that can be use d to commu nicate wit h IP end p oints.
1388	VistaSocke tException : Represen ts an exce ption thro wn during read/write operation s on a soc ket
1389	VistaSocke tTimeOutEx ception: R epresents an excepti on identif ying a tim eout has o ccurred du ring read/ write oper ations.
1390	REF: For m ore inform ation on g ov.va.med. net classe s, see the Javadoc d ocumentati on provide d in the V istALink d istributio n file.Aud it Timer: gov.va.med .monitor.t ime
1391	VistALink uses gov.v a.med.moni tor.time.A uditTimer to capture and log i nformation on the le ngth of ex ecution fo r VistALin k interact ions using lo4j-logg ing capabi lities. Sp ecial logg er gov.va. med.vistal ink.adapte r.spi.Vist aSocketCon nection.Au ditLog is used to ou tput this informatio n. Applica tions can use AuditT imer indep endently i f they wan t to repor t timer in formation for variou s processi ng request s.
1392	Two types of constru ctors can be used to construct the Audit Timer inst ance:
1393	For public AuditTime r(), defau lt logger gov.va.med .monitor.t ime.AuditT imer is us ed.
1394	For public AuditTime r(Logger l ogger), an applicati on-specifi c logger i s used.
1395	AuditTimer logs mill iseconds e lapsed bet ween start () and sto p() calls. The numbe r of elaps ed millise conds can be retriev ed using g etTimeElap sedMillis( ).
1396	Logging ca n be done using eith er log() m ethod:
1397	public voi d log()
1398	public voi d log(Stri ng message ): Since t he logger can be pas sed into t he constru ctor and t he output pattern fo r a specif ic logger can be con figured us ing the lo g4j config uration fi le, there should be no need to pass info message. Instead, d ifferent l oggers sho uld be use d.
1399	Sample Cod e
1400	import gov .va.med.mo nitor.time .AuditTime r;
1401	public cla ss AuditTi merTest {
1402
1403	private st atic Audit Timer time r = null;
1404
1405	private st atic Logge r auditLog ger = Logg er.getLogg er(AuditTi merTest.cl ass.getNam e() + ".Au ditLog");
1406
1407	public sta tic void m ain(String [] args) {
1408
1409
1410	// Initial ize Log4j configurat ion
1411
1412
1413	DOMConfigu rator.conf igureAndWa tch("props /log4jConf ig.xml",10 000);
1414
1415
1416	timer = ne w AuditTim er(auditLo gger);
1417
1418
1419	// Start t imer
1420
1421
1422	timer.star t();
1423
1424
1425	// ... per form your operations
1426
1427
1428	// Stop ti mer
1429
1430
1431	timer.stop ();
1432
1433
1434	// Log ela psed time informatio n
1435
1436
1437	timer.log( );
1438
1439
1440	// Get tim e elapsed if not for logging p urposes
1441
1442
1443	long timeE lapsed = t imer.getTi meElapsedM illis();
1444
1445	}
1446	}
1447	The follow ing is a s nippet fro m the log4 j configur ation file :
1448	<appende r name="au ditTimerTe stConsoleA ppender" c lass="org. apache.log 4j.Console Appender">
1449	<layou t class="o rg.apache. log4j.Patt ernLayout" >
1450
1451	<param nam e="Convers ionPattern " value="A udit time - %m%n"/>
1452	</layo ut>
1453	</append er>
1454	<logger name="gov. va.med.vis talink.uti lities.tes t.AuditTim erTest.Aud itLog" >
1455	<l evel value ="debug" / >
1456
1457	<appender- ref ref="a uditTimerT estConsole Appender"/ >
1458	</logger
1459	Exception: gov.va.me d.exceptio n
1460	ExceptionU tils Class
1461	NOTE: Use of this cl ass (Excep tionUtils) has been deprecated , due to i nclusion o f nested e xceptions in Java 1. 4 and grea ter.All AP Is in the gov.va.med .exception .Exception Utils clas s have bee n deprecat ed:
1462	String get FullStackT race() met hod
1463	Throwable getNestedE xceptionBy Class() me thod
1464	XML: gov.v a.med.xml
1465	XmlUtiliti es Class
1466	NOTE: Use of this cl ass (XmlUt ilities) h as been de precated, due to the high leve l of XML s upport in Java 1.4 a nd greater . However, documenta tion has b een left i n place fo r referenc e.This cla ss contain s a number of static utility m ethods to help devel opers work with XML documents, nodes, at tributes a nd strings . These ut ilities ar e XML-pars er indepen dent.
1467	The tables below des cribe the VistALink utility me thods and variables.
1468	Static Met hod Signat ureDescrip tionString convertXm lToStr(Doc ument doc) Converts a DOM docum ent to a s tringDocum ent getDoc umentForXm lString(
1469	String x ml)Returns an XML DO M Document for the s pecified S tringDocum ent getDoc umentForXm lInputStre am(
1470	InputStr eam xml)Re turns an X ML DOM Doc ument for the specif ied InputS treamAttr getAttr(No de node, S tring attr Name)Retur ns the Att ribute wit h the give n attrName at nodeNo de getNode (String xp athStr, No de node)Re turns the first node at the sp ecified XP ath locati onTable 6‑ 1. VistALi nk Utility Methods
1471	Static Fin al Variabl esDescript ionString XML_HEADER Represents the defau lt header used for a ll xml doc uments tha t communic ate with a n M server via VistA Link. It i s importan t to use t his header as this k eeps the c lient and M server i n sync.Tab le 6‑2. Vi stALink Ut ility Vari ables
1472	How to Use VistALink in J2SE A pplication s
1473	Using Vist ALink to b uild J2SE client/M s erver appl ications i s very sim ilar to us ing VistAL ink in J2E E. The mai n differen ces are in the areas of authen tication a nd obtaini ng a conne ction. Sam ple J2SE a pplication s are prov ided in th e VistALin k distribu tion file, in the sa mples-J2SE folder.
1474	Authentica ting and C onnecting to VistA i n Client-S erver Mode
1475	In J2EE, a pplication s retrieve and retur n VistALin k connecti ons to a c onnection pool. In J 2SE mode, however, V istALink e stablishes a direct, persisten t connecti on on beha lf of the J2SE appli cation to the M serv er. Unless the serve r is shut down, this connectio n remains open until closed by the clien t.
1476	The high-l evel steps to establ ish a Vist ALink conn ection to M in J2SE mode are:
1477	Provide se rver confi guration i nformation to VistAL ink (IP ad dress and port of th e M VistAL ink listen er to conn ect to)
1478	Authentica te the end -user over the conne ction
1479	Execute RP Cs
1480	Close the connection (log out)
1481	VistALink uses the J ava Authen tication a nd Authori zation Ser vice (JAAS ) framewor k for step s 1, 2 and 4 above.
1482	REF: For i nformation on step 3 , see the section “E xecuting R equests
1483	.”JAAS Ove rview
1484	JAAS is a Java plugg able frame work for u ser authen tication a nd authori zation. “P luggabilit y” means t hat differ ent securi ty modules (e.g., au thenticati on modules ) can be a dded or “p lugged in” to an app lication w ithout rec ompiling t he applica tion. Vist ALink uses the JAAS framework to authent icate end- users to a n M/Kernel system, v ia the use rs' custom ary Kernel access an d verify c odes.
1485	A JAAS-com pliant log in module contains a ll of the logic requ ired to au thenticate a user to a given s ystem. The login mod ule class does not i tself, how ever, incl ude the us er interfa ce to gath er authent ication cr edentials (e.g., acc ess and ve rify codes ) from the end-user. Instead, a set of J AAS-compli ant callba cks, along with a JA AS-complia nt callbac k handler, are used to de-coup le the use r interfac e from the login mod ule. VistA Link provi des a JAAS -compatibl e login mo dule and J AAS-compli ant callba cks and ca llback han dlers to p erform a V istA login .
1486	Although t he JAAS fr amework al so provide s authoriz ation capa bilities, VistALink uses JAAS for authen tication o nly. VistA Link does not make a ny use of the permis sion/autho rization p ortions of the JAAS specificat ion at thi s time.
1487	VistALink JAAS Imple mentation
1488	VistaLogin Module
1489	VistALink provides a single JA AS-complia nt login m odule clas s, VistaLo ginModule. As a deve loper, you do not us e this cla ss directl y because your appli cation doe s the foll owing:
1490	Specifies which logi n module t o use, via a JAAS co nfiguratio n file
1491	Creates a LoginConte xt instanc e, and pas ses it a s upported c allback ha ndler inst ance to co llect user input
1492	Invokes th e login me thod of th e LoginCon text class to initia te the log in process for the c onfigured login modu le
1493	Section 50 8 Consider ations
1494	The VistaL oginModule UI has un dergone se ction 508 testing an d been app roved. A b utton on t he main lo gin screen , "Section 508 Infor mation", d ocuments t his.
1495	The login module inh erits colo r and font settings from the p arent appl ication. F or that re ason, we s uggest tha t your cod e invoke t he login m odule's lo gin() meth od after f irst:
1496	Setting th e Swing lo ok-and-fee l to the S ystem look -and-feel classname, and
1497	Calling th e Swing up dateCompon entTreeUI method
1498	JAAS Login Configura tion Overv iew
1499	By default , VistALin k uses the default J AAS config uration re ader to lo ad login c onfigurati ons. The d efault JAA S configur ation read er class l oads login configura tions from a JAAS co nfiguratio n file, wh ich it exp ects to be in a pred efined for mat.
1500	One or mor e configur ation entr ies are de fined in t he JAAS co nfiguratio n file. Th e configur ation file itself ca n have any name, and can be lo cated anyw here. Each entry in the JAAS c onfigurati on file de fines a pa rticular l ogin confi guration. Genericall y, the for mat of thi s file is as follows :
1501	Configurat ionName {
1502
1503
1504	ModuleClas s Flag Mod uleOptions ;
1505
1506	};
1507
1508	Configurat ionName {
1509
1510
1511	ModuleClas s Flag Mod uleOptions ;
1512
1513	};
1514	VistALink- Specific J AAS Login Configurat ion
1515	The follow ing is an example of the JAAS configura tion file format nee ded specif ically for VistALink :
1516	Test {
1517
1518	gov.va.med .vistalink .security. VistaLogin Module req uisite
1519
1520	gov.va.med .vistalink .security. ServerAddr essKey=" AI
1521
1522	gov.va.med .vistalink .security. ServerPort Key="18000 ";
1523	};
1524	Production {
1525
1526	gov.va.med .vistalink .security. VistaLogin Module req uisite
1527
1528	gov.va.med .vistalink .security. ServerAddr essKey=" AI "
1529
1530	gov.va.med .vistalink .security. ServerPort Key="8000" ;
1531	};
1532	This examp le defines two login configura tions, one named "Te st" and on e named "P roduction. " An appli cation use s this nam e (Test or Productio n) as the index to r etrieve a particular configura tion from the JAAS c onfigurati on file.
1533
1534	To configu re a VistA Link login to a Vist A system, configure a single l ogin modul e per logi n configur ation entr y, within each entry 's {braces }, as foll ows:
1535	Name the V istALink l ogin modul e class, i ncluding p ackage nam e:
1536
1537
1538	gov.va.med .vistalink .security. vistalink. VistaLogin Module
1539	Follow wit h a flag i ndicating what actio n to take if login f ails. For VistALink, use requi site.
1540	Follow wit h options for the Vi stALink lo gin module . There ar e two opti ons that m ust be set , in "nam e=value" f ormat:
1541
1542
1543	gov.va.med .vistalink .security. vistalink. ServerAddr essKey
1544
1545
1546	gov.va.med .vistalink .security. vistalink. ServerPort Key
1547
1548	Use quotes around th e server a ddress and server po rt values.
1549	Before the closing b race, end with a sem icolon.
1550	Follow the closing b race with a semicolo n.
1551	REF: For m ore inform ation abou t the JAAS configura tion file format exp ected by t he default JAAS conf iguration file reade r class, s ee:
1552	http://jav a.sun.com/ j2se/1.4.1 /docs/guid e/security /jgss/tuto rials/Logi nConfigFil e.htmlNOTE : It is po ssible to define you r own JAAS configura tion reade r class, i nstead of using the default cl ass. If yo u do this, you are s till respo nsible for providing the packa ge/name of the Vista LoginModul e class, t he JAAS re quisite fl ag, and th e two opti ons requir ed by the VistaLogin Module.Pas sing the J AAS Login Configurat ion(s) to Your JVM
1553	The JAAS L ogin Confi guration n eeds to be passed to the JVM ( and hence to your ap plication) . The JAAS configura tion can b e passed i n two ways :
1554	With the j avax.secur ity.auth.l ogin.Confi guration J ava virtua l machine (JVM) argu ment when launching your appli cation, e. g.:
1555
1556
1557	java -Dja va.securit y.auth.log in.config= jaas.confi g MyApp
1558
1559	In the Jav a security propertie s file.
1560	In most ca ses it is preferable to use th e JVM argu ment, sinc e it allow s the sett ing to be applicatio n-specific rather th an machine -wide.
1561	Selecting the JAAS C onfigurati on From an Applicati on
1562	Once your applicatio n is runni ng, it sho uld select a specifi c configur ation. In order to a llow local administr ation of J AAS config uration fi les, you s hould, in most cases , provide a command- line param eter to al low local administra tors to pa ss a parti cular JAAS configura tion into your appli cation. Fo r example:
1563
1564	java -Djav a.security .auth.logi n.config=j aas.conf MyApp Pro duction
1565	Selecting a VistaLog inModule C allback Ha ndler
1566	In order t o decouple the user interface for logon from the l ogin modul e, the JAA S standard allows lo gin module s such as VistaLogin Module to supply dif ferent cal lback hand lers. Vist ALink supp lies two c allback ha ndler clas ses, one f or an inte ractive lo gon, and o ne for non -interacti ve unit te sting:
1567	CallbackHa ndlerSwing CCOW: for production applicati on use. Pe rforms sin gle-signon if creden tials are already pr esent in C COW user c ontext. Ot herwise, c ollects ac cess code, verify co de, divisi on and "ch ange verif y code" in put via a set of Swi ng dialogs ; stores s ingle sign -on creden tials in C COW user c ontext for subsequen t applicat ion use.
1568	CallbackHa ndlerSwing : for prod uction app lication u se. Collec ts access code, veri fy code, d ivision an d "change verify cod e" input v ia a set o f Swing di alogs.
1569	CallbackHa ndlerUnitT est: for u nit testin g only (no t producti on use). A ccess code , verify c ode, divis ion are pa ssed as pa rameters t o the clas s construc tor, resul ting in a "silent" l ogin suita ble for (n on-interac tive) unit testing. The "chang e verify c ode" funct ionality i s not supp orted.
1570	Your code will need to instant iate one o f these ca llback han dlers as p art of the JAAS Vist ALink logi n. Your co de will th en need to pass the instantiat ed callbac k handler as a param eter to cr eate a JAA S login co ntext (see “Putting the Pieces Together: VistALink JAAS Logi n
1571	,” below.
1572	Benefits o f Passing Parent App lication F rame to Ca llback Han dler
1573	When const ructing/in stantiatin g a VistAL ink callba ck handler , one of t he argumen ts is a re ference to the (java .awt.)Fram e of the p arent appl ication. W e recommen d that the calling a pplication have crea ted a Fram e or desce ndant for itself pri or to invo king login . Benefits to passin g the call ing applic ation's de fined Fram e to the V istALink c allback ha ndler's co nstructor include:
1574	If, during a login t o your app lication, the user t emporarily grants fo cus to ano ther appli cation, an d then ret urns (eith er by choo sing the a pplication in Alt-Ta b, or by c licking th e applicat ion icon i n the task bar), the applicatio n window a nd login d ialog are made visib le with th e login on top, and the login dialog is granted fo cus.
1575	If the log in dialog has focus but the ap p window i s visible beneath it on the sc reen, and the user a ttempts to switch fo cus to the app windo w (from th e login di alog), the login dia log flashe s and keep s focus
1576	If the log in dialog has focus and the us er clicks on the app lication's taskbar i con, the l ogin dialo g keeps fo cus
1577	If the par ent applic ation's Fr ame is not passed, f ocus issue s do not w ork as abo ve which i s problema tic given that the l ogin is a modal dial og.
1578	Putting th e Pieces T ogether: V istALink J AAS Login
1579	Logging in to VistA
1580	The follow ing is an example lo gin. If ap plication execution succeeds t hrough the try block , the user has succe ssfully lo gged in to the speci fied VistA listener.
1581	// variabl e holding LoginConte xt should have appli cation sco pe
1582	// since i t will be needed to log out, l ater on
1583	private Lo ginContext loginCont ext = null ;
1584	try {
1585	// cre ate the ca llback han dler to us e to colle ct user in put
1586
1587	// pass cu rrent Fram e as param eter
1588	Callba ckHandlerS wing cbhSw ing = new CallbackHa ndlerSwing (myFrame);
1589	// create the LoginC ontext to control th e login pr ocess;
1590	// pas s the JAAS configura tion to co nnect to, and the ca llback
1591	// han dler (jaas ConfigName value cou ld be pass ed in from command
1592	// lin e)
1593	loginC ontext = n ew LoginCo ntext(jaas ConfigName , cbhSwing );
1594	// log in to serv er through the Login Context
1595	loginC ontext.log in();
1596	} catch (V istaLoginM oduleExcep tion e) {
1597	JOptio nPane.show MessageDia log(null, e.getMessa ge(), "Log in error",
1598	JOpt ionPane.ER ROR_MESSAG E);
1599	} catch (L oginExcept ion e) {
1600	JOptio nPane.show MessageDia log(null, e.getMessa ge(), "Log in error",
1601	JOpt ionPane.ER ROR_MESSAG E);
1602	}
1603	After Succ essfully L ogging In
1604	Retrieving the Vista KernelPrin cipal
1605	The JAAS s ubject is available from the J AAS LoginC ontext cla ss after a successfu l login.
1606	It contain s a JAAS p rincipal ( user entit y), which holds:
1607	Demographi c informat ion about the logged -in user
1608	The authen ticated Vi stALink co nnection o bject
1609	The follow ing code s hows how t o retrieve the Kerne l principa l after a successful login:
1610	// variabl e holding Kernel pri ncipal may need appl ication sc ope
1611	// since i t will be needed for RPC execu tion
1612	private Vi staKernelP rincipalIm pl userPri ncipal = n ull;
1613	// . . . l ogin code
1614	// get the Kernel pr incipal af ter logon
1615	try {
1616	userPr incipal = VistaKerne lPrincipal Impl.getKe rnelPrinci pal(
1617	logi nContext.g etSubject( ));
1618	} catch ( Foundation sException e) {
1619	JOptio nPane.show MessageDia log(null, e.getMessa ge(), "Log in error",
1620	JOp tionPane.E RROR_MESSA GE);
1621	}
1622	In the fut ure, it is conceivab le that mo re than on e principa l could be contained in the JA AS subject after log in, if mul tiple logi n modules are used. This might happen wh en a compo und login has been c onfigured, requiring several l ogins to c omplete, e .g., one f or a Kerne l M system and one f or a separ ate health data repo sitory.
1623	Only one * Kernel* pr incipal sh ould ever be returne d, however . Use the getKernelP rincipal h elper meth od in the VistaKerne lPrincipal Impl class to retrie ve the sin gle Kernel principal .
1624	Retrieving the Authe nticated C onnection From the P rincipal
1625	To execute RPCs, you need to r etrieve th e authenti cated conn ection. Th e authenti cated conn ection obj ect over w hich you m ake reques ts is stor ed in the Kernel pri ncipal, an d can be r etrieved w ith the ge tAuthentic atedConnec tion metho d.
1626	Once a suc cessful lo gin has be en complet ed, you sh ould retri eve the as sociated a uthenticat ed connect ion from t he Kernel principal. This conn ection is "logged in " to the M system un der the en d-user's i dentity. Y ou can the n use it t o execute requests s uch as RPC s on behal f of the e nd-user.
1627	REF: For m ore inform ation on e xecuting r equests, s ee the cha pter of th is manual titled “Ex ecuting Re quests.” A n example of success ful login appears be low.VistaL inkConnect ion myConn ection =
1628	userPrin cipal.getA uthenticat edConnecti on();
1629	// . . . n ow you can execute r equests
1630	REF: For i nformation on how to use the V istaLinkCo nnection o bject to e xecute req uests, see the secti on “Execut ing RPCs
1631	,” below.R etrieving User Demog raphic Inf ormation
1632	Use the fo llowing pr edefined s tatic KEY* strings t o retrieve user demo graphic va lues via t he Kernel principal' s getUserD emographic Value meth od. For ex ample:
1633	// get the DUZ
1634	String duz = this.us erPrincipa l.getUserD emographic Value(
1635	VistaKer nelPrincip alImpl.KEY _DUZ);
1636	// get the name
1637	String nam e = userPr incipal.ge tUserDemog raphicValu e(
1638	VistaKer nelPrincip alImpl.KEY _NAME_DISP LAY);
1639	The table below show s a comple te set of returned d emographic s informat ion and ke ys.
1640	KeyValueKE Y_DIVISION _IENLogin division s tation IEN KEY_DIVISI ON_STATION _NAMELogin division station na me KEY_DI VISION_STA TION_NUMBE RLogin div ision stat ion number KEY_DTIM EUser time out value KEY_DUZDU Z KEY_LAN GUAGEUser language KEY_NAME_D EGREEUser degree KE Y_NAME_FAM ILYLASTNam e componen t family-l ast KEY_N AME_GIVENF IRSTName c omponent g iven-first KEY_NAME _MIDDLENam e componen t middle KEY_NAME_N EWPERSON01 New Person .01 Field name KEY _NAME_PREF IXName com ponent pre fix KEY_N AME_SUFFIX Name compo nent suffi x KEY_SER VICE_SECTI ONUser ser vice/secti on KEY_NA ME_DISPLAY Concatenat ed standar d name KE Y_TITLEUse r title Ta ble 7‑1. D emographic s Keys and Values
1641	Executing RPCs
1642	Once you h ave a Vist aLinkConne ction conn ection obj ect to wor k with, yo u can exec ute reques ts in exac tly the sa me fashion as for Vi stALink's J2EE mode.
1643	REF: For m ore inform ation, see chapter 4 of this d ocument, “ Executing Requests
1644	.” The ent ire chapte r is valid for J2SE mode.Timeo uts
1645	For inform ation on t imeouts fo r RPC exec ution, see the "Time outs" sect ion of thi s document titled "U sing VistA Link in J2 EE." Most of the inf ormation t here on ti meouts is also valid for the J 2SE mode.
1646	There is o ne signifi cant diffe rence to b e aware of when a ti meout occu rs for a J 2SE VistAL ink connec tion, howe ver. Once a timeout occurs, th e single a uthenticat ed connect ion to the M system is now ren dered unus able. In o rder to pe rform any more actio ns on the M system, the client applicati on will ne ed to re-i nvoke the entire log in process , in order to log in the end u ser again and get to the point where a v alidated, authentica ted connec tion is on ce again a vailable o ver which to execute RPC reque sts.
1647	As such, f or client/ server app lications, it is bes t to set t he longest timeout v alue that can be tol erated wit hin the co ntext of t he RPC its elf as wel l as the s pecific en d-user fun ctionality being exe cuted.
1648	Logging Ou t
1649	Your appli cation sho uld always call the logout met hod of the JAAS Logi nContext c lass to lo g out of V istA befor e exiting. This ensu res that p roper Kern el cleanup (e.g., of the ^TMP global) oc curs on th e M server to which the user w as connect ed.
1650	Logging Ou t of Swing Applicati ons
1651	In a Swing applicati on, the ap plication should alw ays call t he LoginCo ntext's lo gout metho d when the applicati on is shut down. The re are a n umber of w ays an app lication c an be shut down: The user clos es the app lication w indow, the applicati on is term inated fro m the Wind ows contro l panel, e tc.
1652	A good way to catch all of the se shutdow n cases is to implem ent a Wind owAdapter as a windo w listener in the ap plication, and provi de an impl ementation of its wi ndowClosin g method t hat calls the LoginC ontext's l ogout meth od.
1653	For exampl e:
1654	// loginCo ntext has been defin ed earlier , with app lication s cope
1655	// add eve nt listene r to log o ut when wi ndow close s
1656	frame.addW indowListe ner(new Wi ndowAdapte r() {
1657	public void wind owClosing( WindowEven t e) {
1658	my logout();
1659	Sy stem.exit( 0);
1660	}
1661	});
1662	// Method called fro m event ha ndler to p erform log out
1663	private vo id mylogou t() {
1664	// Ker nel logout
1665	if (th is.userPri ncipal != null) {
1666	tr y {
1667	loginCon text.logou t();
1668	} catch (Log inExceptio n e) {
1669	JOptionP ane.showMe ssageDialo g(null, e. getMessage (),
1670	"Logou t error", JOptionPan e.ERROR_ME SSAGE);
1671	}
1672	}
1673	}
1674	Catching L ogin Excep tions
1675	The LoginC ontext log in() and l ogout() me thods only throw exc eptions th at derive from Login Exception. So at a m inimum, wh en executi ng the log in or logo ut methods of a Logi nContext o bject, you r applicat ion needs a try/catc h block to catch Log inExceptio n.
1676	VistaLogin Module Exc eption Hie rarchy
1677	JAAS requi res LoginM odules to throw java x.security .auth.logi n.LoginExc eption fro m JAAS cla sses imple mentation methods. S o the Vist ALink logi n module t hrows exce ptions of type gov.v a.med.vist alink.secu rity.vista link.Vista LoginModul eException , which ex tends java x.security .auth.logi n.LoginExc eption.
1678	The VistaL ink login module pro vides more granular exceptions from Vist aLoginModu leExceptio n, so that your appl ication ca n optional ly filter exceptions at a fine r level of granulari ty. This m eans that your appli cation can detect an d implemen t specific processin g for logi n exceptio n types th at might b e of inter est.
1679	ExceptionD escription VistaLogin ModuleExce ptionLike a LoginExc eption, bu t may cont ain nested exception (s) that w ere the ca use for th e LoginExc eption.Vis taLoginMod uleLoginsD isabledExc eptionLogi ns are dis abled on t he M serve r.VistaLog inModuleNo JobSlotsAv ailableExc eptionJob slot maxim um has bee n exceeded on M serv er.VistaLo ginModuleN oPathToLis tenerExcep tionNo rea chable lis tener was found on t he path re presented by the spe cified IP address an d Port.Vis taLoginMod uleTooMany InvalidAtt emptsExcep tionThe us er tried t o login to o many tim es with in valid cred entials.Vi staLoginMo duleUserCa ncelledExc eptionThe user cance lled the l ogin.Vista LoginModul eUserTimed OutExcepti onThe user timed out of the lo gin.Table 7‑2. VistA Link Login Exception s
1680	For exampl e, if your applicati on is inte rested in whether th e IP and p ort specif ied were " bad" (at l east at th e time the login was attempted ), you can trap for the VistaL oginModule NoPathToLi stener exc eption, in addition to the sta ndard Logi nException . Example:
1681	try {
1682	// cre ate the ca llback han dler to us e to colle ct user in put
1683	Callba ckHandlerS wing cbhSw ing = new CallbackHa ndlerSwing (myFrame);
1684	// cre ate the Lo ginContext to contro l the logi n process.
1685	loginC ontext = n ew LoginCo ntext(serv erAlias, c bhSwing);
1686	// log in to serv er through the Login Context
1687	loginC ontext.log in();
1688	} catch (V istaLoginM oduleLogin sDisabledE xception e ) {
1689	JOptionPan e.showMess ageDialog(
1690	nu ll,
1691	"L ogins are disabled; try later. ",
1692	"L ogin error ",
1693	JO ptionPane. ERROR_MESS AGE);
1694	} catch (L oginExcept ion e) {
1695	JOptio nPane.show MessageDia log(null, e.getMessa ge(), "Log in error",
1696	JOpt ionPane.ER ROR_MESSAG E);
1697	}
1698	CCOW Login Functiona lity
1699	VistALink' s client/s erver logi ns support CCOW-base d single s ign-on, ba sed on the work in t he Single Sign-On/Us er Context (SSO/UC) Project. F or more in formation on CCOW-en abling the logins of client/se rver appli cations, p lease the documentat ion for th e SSO/UC p roject (av ailable on the VDL).
1700	Unit Testi ng and Vis tALink
1701	The login user inter face colle cts end-us er informa tion, incl uding the access and verify co de and div ision numb er. It is separate f rom the lo gic that i mplements login, bec ause of th e pluggabl e JAAS arc hitecture. The user interface is contain ed in a JA AS-complia nt set of callbacks, and the l ogin logic is contai ned in a J AAS-compli ant login module. Th erefore, t he JAAS fr amework ma kes it str aightforwa rd to impl ement alte rnative us er interfa ces for lo gin.
1702	VistALink provides a n alternat ive callba ck handler that impl ements a " silent" (n on-interac tive) logi n suitable for unit testing pu rposes. Th is silent login is n ot suitabl e for any production environme nt. Your a pplication passes th e access a nd verify code, and (optionall y) divisio n to silen tly log in your appl ication. C hanging th e verify c ode is not supported with this callback handler.
1703	For exampl e:
1704	// Connect ion info
1705	String cfg Name = "Pr oduction";
1706	// signon credential s for unit test call back handl er
1707	String acc essCode = "asdf.123" ;
1708	String ver ifyCode = "asdf.456" ;
1709	String div ision = "" ;
1710	try {
1711	// cre ate the "u nit test" callbackha ndler for JAAS login
1712	Callba ckHandlerU nitTest cb hUnitTest =
1713	new CallbackHa ndlerUnitT est(access Code, veri fyCode, di vision);
1714	// cre ate the JA AS LoginCo ntext for login
1715	lc = n ew LoginCo ntext(cfgN ame, cbhUn itTest);
1716	// log in to serv er
1717	lc.log in();
1718	} catch (V istaLoginM oduleExcep tion e) {
1719	JOptionPan e.showMess ageDialog( null, e.ge tMessage() , "Login e rror",
1720	JOption Pane.ERROR _MESSAGE);
1721	} catch (L oginExcept ion e) {
1722	JOptionPan e.showMess ageDialog( null, e.ge tMessage() , "Login e rror", JOp tionPane.E RROR_MESSA GE);
1723	}
1724	Appendix A : Pluggabl e Institut ion Rules
1725	NOTE: This section i s of inter est primar ily to non -VA users of VistALi nk.J2EE Ap plications using Vis tALink nee d the abil ity to sel ect the re source ada pter (conn ector) to execute a remote pro cedure cal l (RPC) on a given M system. T o retrieve the appro priate Vis tALink ada pter, the applicatio n needs to know what JNDI name the adapt er they're intereste d in is re gistered u nder.
1726	VistALink' s institut ion mappin g provides a way for J2EE appl ications t o obtain t he JNDI na me of a Vi stALink ad apter base d on stati on number (the insti tution, st ation, and division number are the piece s of infor mation an applicatio n is likel y to have to identif y an M sys tem it wan ts to conn ect to.)
1727	With VistA Link's ins titution m apping, J2 EE applica tions shou ld not hav e to hard- code conne ctor JNDI names; in most cases they shou ld get the appropria te connect or using a station n umber.
1728	The VA-spe cific impl ementation of instit ution mapp ing rules (gov.va.me d.vistalin k.institut ion.Primar yStationRu lesVHA) ma kes severa l VA-speci fic assump tions, in particular :
1729	Legal stat ion number s in VA ca n be 3 dig its or 5+ digits wit h one exce ption (see nursing h omes below ).
1730	For statio n numbers assigned t o the Aust in Informa tion Techn ology Cent er (AITC) only: If a station n umber has an alpha s uffix, e.g . "200A", the numeri c portion must be "2 00"
1731	For nursin g homes: I f a numeri c station number is 4 digits, the 4th di git must b e a "9"
1732	To replace these rul es with a different rule imple mentation, you can p rovide a n ew impleme ntation of the rules interface (gov.va.m ed.vistali nk.institu tion.IPrim aryStation Rules). To do that:
1733	A new impl ementation of the IP rimaryStat ionRules i nterface m ust be pro vided, and
1734	The packag e/classnam e of the n ew impleme ntation mu st be pass ed in a -D JVM argum ent, "gov. va.med.vis talink.pri mary-stati on-rules-c lass". E.g ., -Dgov.v a.med.vist alink.prim ary-statio n-rules-cl ass=org.te st.Primary StationRul esTest
1735	For an exa mple of an implement ation of i nstitution mapping r ules, you can examin e the sour ce code fo r the Prim aryStation RulesVHA c lass. Also , document ation for the interf ace is pro vided in t he javadoc distribut ed with Vi stALink.
1736	REF: For m ore inform ation on a ctivating a non-VA-s pecific in stitution rules clas s, see the System Ma nagement G uide.Gloss ary
1737	AACFormerl y the Aust in Automat ion Center . Renamed to the Aus tin Inform ation Tech nology Cen ter (AITC) Access Cod eA passwor d used by the Kernel system to identify the user. It is used with the verify cod e. Adapter Another t erm for re source ada pter or co nnector.Ad ministrati on ServerE ach WebLog ic server domain mus t have one server in stance tha t acts as the admini stration s erver. Thi s server i s used to configure all other server ins tances in the domain .AITCAusti n Informat ion Techno logy Cente rAliasAn a lternative filename. Alpha/VMS Alpha: Hew lett Packa rd compute r system
1738	VMS: Virtu al Memory SystemAnon ymous Soft ware Direc tories M directorie s where VH A applicat ion and pa tch zip fi les are pl aced for d istributio n. APIAppl ication Pr ogram Inte rfaceAppli cation Pro xy UserA K ernel user account d esigned fo r use by a n applicat ion rather than an e nd-user.Ap plication ServerSoft ware/hardw are for ha ndling com plex inter actions be tween user s, busines s logic, a nd databas es in tran saction-ba sed, multi -tier appl ications. Applicatio n servers, also know n as app s ervers, pr ovide incr eased avai lability a nd higher performanc e.ASTMAmer ican Socie ty for Tes ting and M aterialsAu thenticati onVerifyin g the iden tity of th e end-user .Authoriza tionGranti ng or deny ing user a ccess or p ermission to perform a functio n.Base Ada pterVersio n 8.1 of W ebLogic in troduced a "link-ref " mechanis m enabling the resou rces of a single "ba se" adapte r to be sh ared by on e or more "linked" a dapters. T he base ad apter is a standalon e adapter that is co mpletely s et up. Its resources (classes, jars, etc .) can be linked to and reused by other resource a dapters (l inked adap ters). The deployer only needs to modify a subset of the lin ked adapte rs’ deploy ment descr iptor sett ings.BEA W ebLogicBEA WebLogic is a J2EE Platform a pplication server. O racle has acquired B EA Systems , Inc. Fro m here for ward it wi ll be refe rred to as Oracle.Ca chéCaché i s an M env ironment, a product of InterSy stems Corp .Cache/VMS Cache: Int erSystems Caché obje ct databas e that run s SQL
1739	VMS: Virtu al Memory SystemCCIC ommon Clie nt Interfa ceCCOWA st andard def ining the use of a t echnique c alled "con text manag ement," pr oviding th e clinicia n with a u nified vie w on infor mation hel d in separ ate and di sparate he althcare a pplication s that ref er to the same patie nt, encoun ter or use r. Classpa thThe path searched by the JVM for class definitio ns. The cl ass path m ay be set by a comma nd-line ar gument to the JVM or via an en vironment variable.C lientCan r efer to bo th the cli ent workst ation and the client portion o f the prog ram runnin g on the w orkstation . Connecti on Factory A J2CA cla ss for cre ating conn ections on request. Connection PoolA cac hed store of connect ion object s that can be availa ble on dem and and re used, incr easing per formance a nd scalabi lity. Vist ALink 1.6 uses conne ction pool ing. Conne ctor A sys tem-level driver tha t integrat es J2EE ap plication servers wi th Enterpr ise Inform ation Syst ems (EIS). VistALink is a J2EE connector module de signed to connect to Java appl ications w ith VistA/ M systems. The term is used in terchangea bly with c onnector m odule, ada pter, adap ter module , and reso urce adapt er.Connect or Proxy U serFor sec urity purp oses, each instance of a J2EE connector must be gr anted acce ss to the M server i t connects to. This is done vi a a Kernel user acco unt set up on the M system. Th is provide s initial authentica tion for t he app ser ver and es tablishes a trusted connection . The M sy stem manag er must se t up the c onnector u ser accoun t and comm unicate th e access c ode, verif y code and listener IP address and port to the J2E E system m anager. CO TSCommerci al, Off-Th e-ShelfCSV Comma-Sepa rated Valu es format DBFDataba se file fo rmat under lying many database applicatio ns (origin ally dBase )DCLDigita l Command Language. An interac tive comma nd and scr ipting lan guage for VMS.Divisi onVHA site s are also called in stitutions . Each ins titution h as a stati on number associated with it. Occasional ly a singl e institut ion is mad e up of mu ltiple sit es, known as divisio ns. To mak e a connec tion, Vist ALink need s a statio n number f rom the en d-user’s N ew Person entry in t he Kernel Site Param eters file . It looks first for a divisio n station number and if it can ’t find on e, uses th e station number ass ociated wi th default instituti on. DSMDig ital Stand ard MUMPS. An M envi ronment, a product o f InterSys tems Corp. DUZA loca l variable holding a number th at identif ies the si gned-on us er. The nu mber is th e Internal Entry Num ber (IEN) of the use r’s record in the NE W PERSON f ile (file #200)EAR f ileEnterpr ise archiv e file. An enterpris e applicat ion archiv e file tha t contains a J2EE ap plication. EISEnterp rise Infor mation Sys temEPHIEle ctronic Pr otected He alth Infor mationFatK AATFat-Cli ent (i.e. Rich clien t) Kernel Authentica tion and A uthorizati onFDAFileM an Data Ar rayFile #1 8System fi le #18 was the precu rsor to th e KERNEL S YSTEMS PAR AMETERS fi le, and is now obsol ete. It us es the sam e number s pace that is now ass igned to V istALink. Therefore, file #18 must be de leted befo re VistALi nk can be installed. GlobalA m ulti-dimen sional dat a storage structure -- the mec hanism for persiste nt data st orage in a MUMPS dat abase.Heal theVet-Vis tAThe VHA is convert ing its MU MPS-based VistA heal thcare sys tem to a n ew J2EE-ba sed platfo rm and app lication s uite. The new system is known as Healthe Vet-VistA. HIPAAHealt h Insuranc e Portabil ity and Ac countabili ty ActIDEI ntegrated developmen t environm ent. A sui te of soft ware tools to suppor t writing software. Institutio nVHA sites are also called ins titutions. Each inst itution ha s a statio n number a ssociated with it. O ccasionall y a single instituti on is made up of mul tiple site s, known a s division s. To make a connect ion, VistA Link needs a station number fr om the end -user’s Ne w Person e ntry in th e KERNEL S YSTEM PARA METERS fil e (#8989.3 ). It look s first fo r a divisi on station number an d if it ca n’t find o ne, uses t he station number as sociated w ith defaul t institut ion. Insti tution Map pingThe Vi stALink 1. 6 release includes a small uti lity that administra tors can u se to asso ciate stat ion number s with JND I names, a nd which a llows runt ime code t o retrieve the a Vis tALink con nection fa ctory base d on stati on number. ISOInforma tion Secur ity Office rJ2CAJ2EE Connector Architectu re. J2CA i s a framew ork for in tegrating J2EE-compl iant appli cation ser vers with Enterprise Informati on Systems , such as the VHA’s VistA/M sy stems. It is the fra mework for J2EE conn ector modu les that p lug into J 2EE applic ation serv ers, such as the Vis tALink ada pter.J2EET he Java 2 Platform, Enterprise Edition ( J2EE) is a n environm ent for de veloping a nd deployi ng enterpr ise applic ations. Th e J2EE pla tform cons ists of a set of ser vices, API s, and pro tocols tha t provide the functi onality fo r developi ng multi-t iered, Web -based app lications. A J2EE Co nnector Ar chitecture specifica tion for b uilding ad apters to connect J2 EE systems to non-J2 EE enterpr ise inform ation syst ems.JAASJa va Authent ication an d Authoriz ation Serv ice. JAAS is a plugg able Java framework for user a uthenticat ion and au thorizatio n, enablin g services to authen ticate and enforce a ccess cont rols upon users. JAR fileJava archive f ile. It is a file fo rmat based on the ZI P file for mat, used to aggrega te many fi les into o ne. Java L ibraryA li brary of J ava classe s usually distribute d in JAR f ormat.Java docJavadoc is a tool for gener ating API documentat ion in HTM L format f rom doc co mments in source cod e. Documen tation pro duced with this tool is typica lly called Javadoc.J BossJBoss is a free software / open sour ce Java EE -based app lication s erver.JCA CCIJ2EE Co nnector Ar chitecture Common Cl ient Inter faceJDKJav a Developm ent Kit. A set of pr ogramming tools for developing Java appl ications.J MXJava Man agement eX tensions. A java spe cification for build ing manage ability in to java ap plications , includin g J2EE-bas ed ones.JN DIJava Nam ing and Di rectory In terface. A protocol to a set o f APIs for multiple naming and directory services. JREThe Jav a Runtime Environmen t consists of the Ja va virtual machine, the Java p latform co re classes , and supp orting fil es. JRE is bundled w ith the JD K but also available packaged separately .JSPJava S erver Page s. A langu age for bu ilding web interface s for inte racting wi th web app lications. JVMJava V irtual Mac hine. The JVM interp rets compi led Java b inary code (byte cod e) for spe cific comp uter hardw are.KAAJEE Kernel Aut henticatio n and Auth orization for Java 2 Enterpris e EditionK ernelKerne l function s as an in termediary between t he host M operating system and VistA M a pplication s. It cons ists of a standard u ser and pr ogram inte rface and a set of u tilities f or perform ing basic VA compute r system t asks, e.g. , Menu Man ager, Task Manager, Device Han dler, and security.K IDSKernel Installati on and Dis tribution System. Th e VistA/M module for exporting new VistA software packages.L DAPAcronym for Light weight Dir ectory Acc ess Protoc ol. LDAP i s an open protocol t hat permit s applicat ions runni ng on vari ous platfo rms to acc ess inform ation from directori es hosted by any typ e of serve r. Linked AdapterVer sion 8.1 o f WebLogic introduce d a "link- ref" mecha nism enabl ing the re sources of a single "base" ada pter to be shared by one or mo re "linked " adapters . The base adapter i s a standa lone adapt er that is completel y set up. Its resour ces (class es, jars, etc.) can be linked to and reu sed by oth er resourc e adapters (linked a dapters). The deploy er only ne eds to mod ify a subs et of link ed adapter s’ deploym ent descri ptor setti ngs.LinuxA n open-sou rce operat ing system that runs on variou s types of hardware platforms. HealtheVe t-VistA se rvers use both Linux and Windo ws operati ng systems . Listener A socket r outine tha t runs con tinuously at a speci fied port to field i ncoming re quests. It sends req uests to a front con troller fo r processi ng. The co ntroller r eturns its response to the cli ent throug h the same port. The listener creates a separate t hread for each reque st, so it can accept and forwa rd request s from mul tiple clie nts concur rently.log 4J Utility An open-so urce loggi ng package distribut ed under t he Apache Software l icense. Re viewing lo g files pr oduced at runtime ca n be helpf ul in debu gging and troublesho oting. log gerIn log4 j, a logge r is a nam ed entry i n a hierar chy of log gers. The names in t he hierarc hy typical ly follow Java packa ge naming convention s. Applica tion code can select a particu lar logger by name t o write ou tput to, a nd adminis trators ca n configur e where a particular named log ger’s outp ut is sent .M (MUMPS) Massachuse tts Genera l Hospital Utility M ulti-progr amming Sys tem, abbre viated M. M is a hig h-level pr ocedural p rogramming computer language, especially helpful f or manipul ating text ual data.M anaged Ser verA serve r instance in a WebL ogic domai n that is not an adm inistratio n server, i.e., not used to co nfigure al l other se rver insta nces in th e domain.M BeansIn th e Java pro gramming l anguage, a n MBean (m anaged bea n) is a Ja va object that repre sents a ma nageable r esource, s uch as an applicatio n, a servi ce, a comp onent, or a device. MBeans mus t be concr ete Java c lasses.Mes sagingA fr amework fo r one appl ication to asynchron ously deli ver data t o another applicatio n, typical ly using a queuing m echanism.M ultipleA V A FileMan data type that allow s more tha n one valu e for a si ngle entry . Namespac e A unique 2-4 chara cter prefi x for each VistA pac kage. The DBA assign s this cha racter str ing for de velopers t o use in n aming a pa ckage’s ro utines, op tions, and other ele ments. The namespace includes a number s pace, a pr e-defined range of n umbers tha t package files must stay with in. New Pe rson FileT he New Per son file c ontains in formation for all va lid users on an M sy stem. NIST National I nstitute f or Standar ds and Tec hnologyOIO ffice of I nformation Oracle Web LogicOracl e WebLogic is a J2EE Platform applicatio n server. Oracle has acquired BEA System s, Inc. OS Operating SystemPatc hAn update to a Vist A software package t hat contai ns an enha ncement or bug fix. Patches ca n include code updat es, docume ntation up dates, and informati on updates . Patches are applie d to the p rograms on M systems by IRM se rvices.PHI Protected Health Inf ormationPl ug-inA com ponent tha t can inte ract with or be adde d to an ap plication without re compiling the applic ation.ra.x ml ra.xml is the sta ndard J2EE deploymen t descript or for J2C A connecto rs. It des cribes con nector-rel ated attri butes and its deploy ment prope rties usin g a standa rd DTD (Do cument Typ e Definiti on) from S un. Re-aut henticatio nWhen usin g a J2CA c onnector, the proces s of switc hing the s ecurity co ntext of t he connect or from th e original applicati on connect or "user" to the act ual end-us er. This i s done by the callin g applicat ion supply ing a prop er set of user crede ntials.Res ource Adap terJ2EE re source ada pter modul es are sys tem-level drivers th at integra te J2EE ap plication servers wi th Enterpr ise Inform ation Syst ems (EIS). This term is used i nterchange ably with resource a dapter and connector .RMRequire ments Mana gementRout ineA progr am or sequ ence of co mputer ins tructions that may h ave some g eneral or frequent u se. M rout ines are g roups of p rogram lin es that ar e saved, l oaded, and called as a single unit with a specific name.RPCR emote Proc edure Call . A define d call to M code tha t runs on an M serve r. A clien t applicat ion, throu gh the RPC Broker, c an make a call to th e M server and execu te an RPC on the M s erver. Thr ough this mechanism a client a pplication can send data to an M server, execute c ode on an M server, or retriev e data fro m an M ser verRPC Bro kerThe RPC Broker is a client/ server sys tem within VistA. It establish es a commo n and cons istent fra mework for client-se rver appli cations to communica te and exc hange data with Vist A/M server s.RPC Secu rityAll RP Cs are sec ured with an RPC con text (a "B "-type opt ion). An e nd-user ex ecuting an RPC must have the " B"-type op tion assoc iated with the RPC i n the user ’s menu tr ee. Otherw ise an exc eption is thrown. SA DSoftware Architectu re Documen tSE&ISoftw are Engine ering & In tegrationS ervletA Ja va program that resi des on a s erver and executes r equests fr om client web pages. SocketAn operating system obj ect that c onnects ap plication requests t o network protocols. SPIJ2CA s ervice pro vider inte rface Ser vice-Level ContractS RSSoftware Requireme nts Specif icationSSH
1740	Secure She ll or SSH is a netwo rk protoco l that all ows data t o be excha nged using a secure channel be tween two networked devices. U sed primar ily on Lin ux and Uni x based sy stems to a ccess shel l accounts , SSH was designed a s a replac ement for Telnet and other ins ecure remo te shells, which sen d informat ion, notab ly passwor ds, in pla intext, le aving them open for intercepti on. The en cryption u sed by SSH provides confidenti ality and integrity of data ov er an inse cure netwo rk, such a s the Inte rnet.TCP/I PTransmiss ion Contro l Protocol (TCP) and the Inter net Protoc ol (IP)Ter mDefinitio nTXTText f ile format UMLUnifie d Modeling Language is a stand ardized sp ecificatio n language for objec t modeling .VADepartm ent of Vet erans Affa irsVACOVet erans Affa irs Centra l OfficeVe rify CodeA password used in ta ndem with the access code to p rovide sec ure user a ccess. The Kernel’s Sign-on/Se curity sys tem uses t he verify code to va lidate the user's id entity.Vis tAVeterans Health In formation Systems an d Technolo gy Archite cture. The VHA’s por tfolio of M-based ap plication software u sed by all VA medica l centers and associ ated facil ities.Vist ALink Libr ariesClass es written specifica lly for Vi stALink.VL VistaLink is a runti me and dev elopment t ool provid ing connec tion and d ata conver sion betwe en Java an d M applic ations in client-ser ver and n- tier archi tectures, to which t his docume nt describ es the arc hitecture and design . VMSVirtu al Memory System. An operating system, o riginally designed b y DEC (now owned by Hewlett-Pa ckard), th at operate s on the V AX and Alp ha archite ctures. VP IDVA Perso n Identifi er. A new enterprise -level ide ntifier un iquely ide ntifying V A ‘persons ’ across t he entire VA domain. WAR fileWe b archive file. Cont ains the c lass files for servl ets and JS Ps.WebLogi cWebLogic is a J2EE Platform a pplication server.We bLogic Ser verA J2EE applicatio n server m anufacture d by Oracl e Systems. WebSphere WebSphere Applicatio n Server ( WAS) is a J2EE appli cation ser ver manufa ctured by IBM Corp.X LSMicrosof t Office X L workshee t and work book file formatXMLE xtensible Markup Lan guageXmlBe ansXMLBean s is a Jav a-to-XML b inding fra mework whi ch is part of the Ap ache Softw are Founda tion XML p roject.XOB Namespace The VistAL ink namesp ace. All V istALink p rograms an d their el ements beg in with th e characte rs "XOB."R EF: For a comprehens ive list o f commonly used infr astructure - and secu rity-relat ed terms a nd definit ions, plea se visit t he Securit y and Othe r Common S ervices Gl ossary Web page at t he followi ng Web add ressXE "Gl ossary:Hom e Page Web Address, Glossary"
1741
1742	XE "S&OCS: Glossary:H ome Page W eb Address , Glossary "
1743
1744	XE "Web Pa ges:Glossa ry Home Pa ge Web Add ress, Glos sary"
1745
1746	XE "Home P ages:Gloss ary Home P age Web Ad dress, Glo ssary"
1747
1748	XE "URLs:G lossary Ho me Page We b Address, Glossary" :
1749	http:// URL iss/glossa ry.asp
1750	For a comp rehensive list of ac ronyms, pl ease visit the Secur ity and Ot her Common Services Acronyms W eb site at the follo wing Web a ddressXE " Acronyms : Home Page Web Addres s, Glossar y"
1751
1752	XE "S&OCS: Acronyms:H ome Page W eb Address , Glossary "
1753
1754	XE "Web Pa ges:Acrony ms Home Pa ge Web Add ress, Glos sary"
1755
1756	XE "Home P ages:Acron yms Home P age Web Ad dress, Glo ssary"
1757
1758	XE "URLs:A cronyms Ho me Page We b Address, Glossary" :
1759	http://URL /iss/acron yms/index. asp� http: //en.wikip edia.org/w iki/Secure _Shell














































1760